crewforth 3.1.0-rc.1 → 3.1.0-rc.3

package/CHANGELOG.md

@@ -80,8 +80,16 @@ versioning follows [SemVer](https://semver.org/).
   rules of its architecture guide, the rebuild cost model, layout by window size and never by device type, isolates,
   platform channels, generated localisations, the mix of unit, widget, integration and golden tests, measuring in
   profile mode on a real device, and a release without a secret in it. Its done-definition is `dart format
-  --set-exit-if-changed .`, `flutter analyze`, `flutter test` and the accessibility guideline test. Every rule was
-  checked against Flutter's and Dart's own documentation; the sources are in the skill's `references/`. 40 skills now.
+  --set-exit-if-changed .`, `flutter analyze`, `flutter test` and the accessibility guideline test. It also holds
+  what a real app taught it: panes that split at a foldable's hinge, a list and a detail whose selection and typed
+  input survive a change of window class, a widget test at one width of each window class, figures of one width for
+  amounts, case changed by the language's rules, no inline text (one central file is enough for one language), a
+  domain layer with no `package:flutter` import, goldens made in one pinned container, and a store build that
+  refuses the flag of a closed feature. For an app that holds sensitive data: an encrypted database, its key in the
+  platform's secure store, both kept out of backup and device transfer, every network call through a transport bound to its own allowed hosts,
+  and no ad in a window that shows a sensitive screen. The rules were checked against Flutter's, Dart's and the
+  named packages' and platforms' own pages; the sources, and what was not checked, are in the skill's `references/`.
+  40 skills now.
 - **In `auto` and `dontAsk`, your own message approves a commit or a push.** Those modes answer a permission prompt
   with software, so the commit gate fails closed there and the only way through was to switch mode for every commit.
   Now a message that is nothing but `approve: commit`, `approve: push` or `approve: commit+push` (`onay:` works too)
@@ -110,9 +118,39 @@ versioning follows [SemVer](https://semver.org/).
 - **Studio: a layout for a narrow window.** Below 640 px the panel is one column: the navigator is a drawer, the
   inspector and the conversation take the whole stage and stop above the dock. Checked in a narrow desktop browser
   window; not measured on a phone.
+- **Studio: what a session spent.** A summary box on the canvas and one line in the navigator give the session's
+  time, its tokens (agents included) and an estimate of the cost, such as `51m · 2.8M · ~$3.22`. The cost is an
+  estimate at API list price and reads as one (a leading `~`; on a subscription it is not what you are billed). The
+  prices are one table, read from the pricing page on 2026-10-08; a model with no row in it shows `—`, never a guess.
+  Not checked against an invoice.
+- **Studio: background work is shown.** A Bash command sent to the background is listed on its session (`1 in
+  background` on the card, **In the background** in the inspector) until the notice that ends it arrives.
+- **Studio: a question waiting in a terminal is named.** For a session started in a terminal, a permission question
+  can only be answered there; the view now says so, with the tool and the command: `Waiting for an answer in the
+  terminal: Bash · npm run build`.
+- **Studio: the inspector can be resized** (drag its left edge, arrow keys, double-click for the default; 280 to
+  720 px, remembered).
 
 ### Changed
 
+- **Studio: agents are named by their role.** `crew-backend-expert` reads Backend, `general-purpose` General Purpose,
+  in the graph, the Timeline, the List, the dock, the inspector and the conversation; the declared type is under the
+  name in the inspector and on hover. A task cut short on a card is said in full on hover.
+- **Studio: a group of agents opens beside itself.** Several agents of one type are one card; in a window of 1024 px
+  and up, clicking it puts its agents in the next column as ordinary cards, and opening another group folds the
+  first. Below that width it opens downward as before.
+- **In `auto` and `dontAsk`, a refused commit or push says what to ask and what to send back.** The refusal was a
+  paragraph with the approval text somewhere inside it, and the question the model made of it was as long. It now
+  asks for one shape: the commit message in one code block and, under it, one line with the exact text to send,
+  `approve: commit`, `approve: push` or `approve: commit+push` (`onay: …`), named for the call that was refused. A
+  sentence that says yes is still not an approval, and nothing about what an approval covers has changed.
+- **Where the approval cannot be recorded, the refusal says so.** The record is written by `prompt-approval.sh`. In a
+  session whose settings do not wire it (a worktree that carries an older Crewforth, for one) the message
+  `approve: commit` recorded nothing, and the refusal went on asking for it. The gate now reads the settings it can
+  see (the plugin's `hooks.json`, the project's `settings.json` and `settings.local.json`, the user's
+  `settings.json`) and, when none wires the hook, says the approval path is closed in this session and names the
+  two ways that work: Shift+Tab, or your own terminal. The command is refused either way. `doctor.sh` warns about
+  the same thing, and about a worktree of the repository that carries another Crewforth version.
 - **After a final release, npm's `next` no longer names something older than `latest`.** A final moved `latest`
   only, so `npx crewforth@next` went on installing the rc before it. The release now moves `next` to the final when
   what `next` names is older; an rc of a later version stays where it is.
@@ -197,6 +235,16 @@ versioning follows [SemVer](https://semver.org/).
   the same (measured on Windows, in a real session), and the conversation says who refused it. Known limit: the dock
   can ask about a call that another gate refuses anyway.
 
+### Fixed
+
+- **Studio: full screen keeps its panels.** In full screen the navigator, the inspector and the conversation could
+  not be opened, so a selected agent showed nothing and a request under "Needs you" could not be answered. A style
+  rule hid every panel there; it is gone, and full screen now only takes the browser away.
+- **Studio: a background agent that is still working is no longer drawn "Done".** Claude Code sends a `completed`
+  notice each time a background agent stops, and the agent can be resumed after it; Studio took the first notice as
+  final. A notice now stands only until the agent writes to its transcript again, and while its session is running
+  an agent in the middle of a turn is drawn Running.
+
 ## [3.0.4] — 2026-10-05
 
 ### Security

package/kit/agents/crew-commit-agent.md

@@ -87,8 +87,11 @@ On a mixed/non-atomic diff, **propose a split**; do not commit before approval (
   The tool-level gate `guard-bash.sh` intercepts commit/push in **every** permission mode: in normal modes it raises an
   approval prompt only the user can answer — so present the message FIRST, then run the commit yourself and let the user
   approve it at the prompt. Never hand the user a command to paste into their own terminal. In `auto` and `dontAsk`
-  the prompt reaches nobody: stage, present the message, and the user approves by sending a message that is only
-  `approve: commit` (`approve: push`, `approve: commit+push`; `onay:` too). It covers what is staged on that HEAD.
+  the prompt reaches nobody: stage, then ask in this shape and with nothing after it — the message in ONE code block,
+  and under it one line in the user's language: "If you approve, write only this: `approve: commit`" (`approve: push`,
+  `approve: commit+push`; `onay:` too). The user approves by sending that text alone; a sentence that says yes is not an
+  approval. It covers what is staged on that HEAD. If the gate says the approval path is closed in this session (the
+  recording hook is not wired), say so and offer Shift+Tab or their own terminal instead.
   Then run `git commit -m '…'` alone in its call (single-quoted, or from a here-document with a quoted delimiter),
   and a push as `git push <remote> <branch>`. Never write that message yourself. Under `plan` and
   `bypassPermissions` the gate fails closed; there the user must switch modes or pre-authorise with

package/kit/eval/doctor.sh

@@ -96,6 +96,10 @@ _mt() {
       'SessionStart not wired — session rehydration after /compact or /clear is inactive (update Crewforth)') s="SessionStart bağlı değil — /compact ya da /clear sonrasında oturum toparlanmıyor (Crewforth'u güncelleyin)" ;;
       'SessionStart wired (session rehydration active)') s='SessionStart bağlı (oturum toparlama devrede)' ;;
       'settings.json is invalid JSON') s='settings.json geçersiz JSON' ;;
+      'approval by your own message is wired (auto / dontAsk: approve: commit)') s='kendi mesajınızla onay bağlı (auto / dontAsk: onay: commit)' ;;
+      "settings.json wires prompt-approval.sh but the script is missing — in auto and dontAsk the message 'approve: commit' records nothing; switch mode with Shift+Tab or commit in your own terminal (update Crewforth)") s="settings.json prompt-approval.sh'i bağlıyor ama betik yok — auto ve dontAsk modunda 'onay: commit' mesajı hiçbir şey kaydetmez; Shift+Tab ile mod değiştirin ya da kendi terminalinizden commit edin (Crewforth'u güncelleyin)" ;;
+      "prompt-approval.sh is not wired on UserPromptSubmit — in auto and dontAsk the message 'approve: commit' records nothing; switch mode with Shift+Tab or commit in your own terminal (update Crewforth)") s="prompt-approval.sh UserPromptSubmit'e bağlı değil — auto ve dontAsk modunda 'onay: commit' mesajı hiçbir şey kaydetmez; Shift+Tab ile mod değiştirin ya da kendi terminalinizden commit edin (Crewforth'u güncelleyin)" ;;
+      "worktree %s carries Crewforth %s, this one %s — a session there runs that version's gates and approval path (update Crewforth there)") s="%s worktree'sinde Crewforth %s var, burada %s — orada açılan oturum o sürümün kapılarını ve onay yolunu koşar (Crewforth'u orada güncelleyin)" ;;
       "fix the syntax by hand — restoring Crewforth's file would drop any hooks you added") s="sözdizimini elle düzeltin — Crewforth'un dosyasını geri yüklemek eklediğiniz hook'ları siler" ;;
       'settings.json wires hooks through the %s placeholder — on Windows its separators are stripped before bash runs, so NO hook launches and every gate is silently absent') s="settings.json hook'ları %s yer tutucusuyla bağlıyor — Windows'ta ayırıcılar bash çalışmadan silinir, bu yüzden HİÇBİR hook başlamaz ve bütün kapılar sessizce yok olur" ;;
       'update Crewforth (npx crewforth adopt) — hook commands become:') s="Crewforth'u güncelleyin (npx crewforth adopt) — hook komutları şu olur:" ;;
@@ -349,6 +353,14 @@ if [ -f "$S" ]; then
                     || bad "settings.json hook events empty or missing:%s — those gates won't fire" "restore settings.json from Crewforth (npx crewforth update)" "$EMPTY"
     sn="$(awk -v op=len -v path=hooks.SessionStart -f "$SJ" "$S" 2>/dev/null)"
     case "$sn" in ''|0) warn "SessionStart not wired — session rehydration after /compact or /clear is inactive (update Crewforth)" ;; *) ok "SessionStart wired (session rehydration active)" ;; esac
+    # In auto and dontAsk the only approval is the user's own message, and ONE hook records it. Where it is not wired
+    # the gate stays closed and a message 'approve: commit' records nothing (field report: a worktree on an older
+    # Crewforth). A warning, not a failure: commit and push still cannot happen without the user.
+    case "$(awk -v op=get -v path=hooks.UserPromptSubmit -f "$SJ" "$S" 2>/dev/null)" in
+      *prompt-approval.sh*) if [ -f .claude/hooks/prompt-approval.sh ]; then ok "approval by your own message is wired (auto / dontAsk: approve: commit)"
+                            else warn "settings.json wires prompt-approval.sh but the script is missing — in auto and dontAsk the message 'approve: commit' records nothing; switch mode with Shift+Tab or commit in your own terminal (update Crewforth)"; fi ;;
+      *) warn "prompt-approval.sh is not wired on UserPromptSubmit — in auto and dontAsk the message 'approve: commit' records nothing; switch mode with Shift+Tab or commit in your own terminal (update Crewforth)" ;;
+    esac
   else bad "settings.json is invalid JSON" "fix the syntax by hand — restoring Crewforth's file would drop any hooks you added"; fi
   # `${CLAUDE_PROJECT_DIR}` inside a hook command is the shape that breaks on Windows, and it breaks invisibly.
   # Claude Code substitutes that placeholder into the command STRING before any shell sees it; on Windows the
@@ -370,6 +382,20 @@ if [ -f "$S" ]; then
 else
   bad "settings.json missing — the tool-level gates (commit approval, guards, context) are INACTIVE" "reinstall Crewforth"
 fi
+# 4b) Another worktree of this repository on another Crewforth. A session that moves there runs THAT version's hooks
+#     against this one's expectations: its gates, its approval path (3.0 has none for auto mode). `.claude/` is
+#     tracked in some projects, so a worktree cut from an older branch carries the older kit.
+if [ -f .claude/VERSION ] && git rev-parse --git-dir >/dev/null 2>&1; then
+  _wv0="$(head -1 .claude/VERSION 2>/dev/null | tr -cd '0-9A-Za-z.-')"; _wt0="$(git rev-parse --show-toplevel 2>/dev/null)"
+  while IFS= read -r _wl; do
+    case "$_wl" in "worktree "*) _wp="${_wl#worktree }" ;; *) continue ;; esac
+    [ "$_wp" != "$_wt0" ] && [ -f "$_wp/.claude/VERSION" ] || continue
+    _wv="$(head -1 "$_wp/.claude/VERSION" 2>/dev/null | tr -cd '0-9A-Za-z.-')"
+    [ "$_wv" = "$_wv0" ] || warn "worktree %s carries Crewforth %s, this one %s — a session there runs that version's gates and approval path (update Crewforth there)" "$_wp" "${_wv:-?}" "$_wv0"
+  done <<EOF_WT
+$(git worktree list --porcelain 2>/dev/null)
+EOF_WT
+fi
 
 # 4a) Skill listing budget. Claude Code puts a listing of every model-invocable skill's name and description into
 #     context each turn and caps it at skillListingBudgetFraction of the context window (default 0.01); over the

package/kit/eval/smoke-test.sh

@@ -6167,6 +6167,35 @@ GBCP
   ( cd "$DTMP" && env -u CREW_LANG CREW_I18N_MISS="$DTMP/miss2" bash .claude/eval/doctor-twin.sh >/dev/null 2>&1 )
   grep -qx 'planted line with no translation' "$DTMP/miss2" && pass "twin: a planted untranslated line is named by the miss list" \
     || fail "twin: the miss list did not name a planted untranslated line — the empty list above proves nothing"
+  # THE APPROVAL PATH, AS DOCTOR SEES IT. In auto and dontAsk one hook records the user's own message; where it is
+  # not wired, or another worktree carries another Crewforth, the gate stays closed and its advice used to be wrong
+  # (field report, 3.1.0-rc.2). Four states of the wiring and two of the worktree, each read from doctor's own lines.
+  DAP="$(mktemp -d)"; DAP="$(cd -P "$DAP" && pwd)"; mkdir -p "$DAP/p/.claude"
+  for d in eval hooks; do [ -d "$ROOT/$d" ] && cp -R "$ROOT/$d" "$DAP/p/.claude/$d"; done
+  cp "$ROOT/settings.json" "$DAP/p/.claude/settings.json" 2>/dev/null; echo 3.1.0 > "$DAP/p/.claude/VERSION"
+  ( cd "$DAP/p" && git init -q . && git config user.email t@example.com && git config user.name t && git config core.hooksPath /dev/null \
+    && echo x > f && git add f && git commit -qm init && git worktree add -q "$DAP/old" -b old ) >/dev/null 2>&1
+  _dap(){ ( cd "$DAP/p" && CREW_LANG=en bash .claude/eval/doctor.sh 2>/dev/null ); }
+  if [ ! -d "$DAP/old" ]; then fail "FIXTURE: the linked worktree for doctor's approval cases was not created"
+  else
+    _d1="$(_dap)"
+    case "$_d1" in *"approval by your own message is wired"*) case "$_d1" in *"carries Crewforth"*|*"records nothing"*) fail "doctor warned about the approval path on a healthy install with a worktree that carries no Crewforth" ;;
+                     *) pass "doctor: the approval hook is reported wired on a fresh install, with no warning" ;; esac ;;
+                   *) fail "doctor did not report the approval hook as wired on a fresh install" ;; esac
+    mkdir -p "$DAP/old/.claude"; echo 3.1.0 > "$DAP/old/.claude/VERSION"; _d2="$(_dap)"
+    echo 3.0.4 > "$DAP/old/.claude/VERSION"; _d3="$(_dap)"
+    case "$_d2" in *"carries Crewforth"*) fail "doctor warned about a worktree on the SAME Crewforth" ;; *)
+      # The path is git's own spelling (`C:/…` on Windows, where this script says `/tmp/…`), so only its last part is read.
+      case "$_d3" in *"/old carries Crewforth 3.0.4, this one 3.1.0"*) pass "doctor: a worktree on another Crewforth is named with both versions; one on the same version is not" ;;
+                     *) fail "doctor did not name a worktree that carries Crewforth 3.0.4 beside this 3.1.0" ;; esac ;; esac
+    mv "$DAP/p/.claude/hooks/prompt-approval.sh" "$DAP/pa.sh"; _d4="$(_dap)"; mv "$DAP/pa.sh" "$DAP/p/.claude/hooks/prompt-approval.sh"
+    case "$_d4" in *"wires prompt-approval.sh but the script is missing"*) pass "doctor: wired with the script missing is a warning that names the two ways that still work" ;;
+                   *) fail "doctor did not warn when prompt-approval.sh is wired and missing" ;; esac
+    sed 's/prompt-approval\.sh/some-other.sh/' "$DAP/p/.claude/settings.json" > "$DAP/s.tmp" && mv "$DAP/s.tmp" "$DAP/p/.claude/settings.json"; _d5="$(_dap)"
+    case "$_d5" in *"prompt-approval.sh is not wired on UserPromptSubmit"*"Shift+Tab"*) pass "doctor: an install whose settings do not wire the approval hook is warned, with Shift+Tab and the terminal named" ;;
+                   *) fail "doctor did not warn when prompt-approval.sh is not wired on UserPromptSubmit" ;; esac
+  fi
+  rm -rf "$DAP"
   # WHAT git IS POINTED AT. .claude/git-shim is Crewforth's too: the updater points git there when the project has a
   # hook chain of its own, and each shim runs Crewforth's hook and then the project's. Doctor did not know it: on such a
   # project it answered "not Crewforth's hooks" and advised `git config core.hooksPath .claude/hooks`, the command that
@@ -6897,10 +6926,11 @@ _pa_new(){  # a fresh repository on branch feat/x with one remote, a staged chan
     && git config user.name t && git config core.hooksPath /dev/null && git checkout -q -b feat/x && echo one > a.txt && git add a.txt \
     && git commit -qm init && git remote add origin "$_PA/remote.git" && echo two >> a.txt && git add a.txt ) >/dev/null 2>&1
   _pa_review; }
+# The fixture wires the recording hook, as an install does (_pa_review writes the settings file): the refusal reads it.
 # The remote's address AS GIT SPELLS IT. On Git Bash git answers `C:/…` where the shell says `/c/…`, so an address is
 # never compared against a path this script built: it is asked back from git (_pa_url), and "elsewhere" is derived from it.
 _pa_url(){ ( cd "$_paw" && git remote get-url --push "${1:-origin}" 2>/dev/null ); }
-_pa_review(){ ( cd "$_paw" && mkdir -p .claude && printf '{"diff_oid":"%s","head":"%s"}\n' "$(git diff --cached | git hash-object --stdin)" "$(git rev-parse --verify --quiet HEAD)" > .claude/review-pass.json ); }
+_pa_review(){ ( cd "$_paw" && mkdir -p .claude && printf '%s' '{"hooks":{"UserPromptSubmit":[{"hooks":[{"type":"command","command":"bash .claude/hooks/prompt-approval.sh"}]}]}}' > .claude/settings.json && printf '{"diff_oid":"%s","head":"%s"}\n' "$(git diff --cached | git hash-object --stdin)" "$(git rev-parse --verify --quiet HEAD)" > .claude/review-pass.json ); }
 _pa_rec="$_paw/.git/crewforth-approval"
 # $1 = mode, $2 = the prompt AS JSON TEXT (already escaped), $3 = cwd (default: the repository)
 _pa_say(){ printf '{"session_id":"s","cwd":"%s","permission_mode":"%s","hook_event_name":"UserPromptSubmit","prompt":"%s"}' "${3:-$_paw}" "$1" "$2" \
@@ -6917,7 +6947,7 @@ _pa_op(){ sed -n 's/^op=//p' "$_pa_rec" 2>/dev/null; }
 if [ "$UNITS" != 1 ]; then
   # The cases below feed payloads to the two hooks; like the other gate unit cases they belong to the source run.
   # An installed project keeps the two pins after them: the shared definitions and the wiring.
-  skip scope "approval by the user's own message: the unit cases run in the source checkout (scope=install)" 37
+  skip scope "approval by the user's own message: the unit cases run in the source checkout (scope=install)" 39
 elif [ ! -f "$HOOKS/prompt-approval.sh" ]; then
   fail "hooks/prompt-approval.sh is missing — in auto and dontAsk nothing can turn the user's own yes into an approval"
 else
@@ -7458,6 +7488,43 @@ else
   if [ "$_pc2" -ge 5 ] && [ "$_pc2" -le 12 ]; then pass "an approval costs it a handful of git calls ($_pc2 external commands for commit+push), paid once per approval"
   else fail "the approval hook ran $_pc2 external commands for one commit+push approval — outside 5..12, so either it measured nothing or it grew"; fi
 fi
+# ---- what the refusal tells the model to do (3.1.0, field report) ---------------------------------------------
+# In auto the refusal is the only instruction the model gets, and the user sees what the model makes of it. Two
+# things are pinned: with the recording hook wired it asks for one shape (the message in one block, one line with
+# the exact text to send back, the operation of THIS call); with the hook not wired it says the path is closed and
+# does not tell anyone to type an approval. Verdicts do not move: each case is refused, and a matching record is
+# still allowed whatever the wiring says. The case sets CLAUDE_PROJECT_DIR and HOME itself: both are read.
+_pa_new; mkdir -p "$_PA/home"
+_pa_gate(){ printf '{"session_id":"s","cwd":"%s","permission_mode":"%s","tool_name":"Bash","tool_input":{"command":"%s"}}' "$_paw" "$1" "$2" > "$_PA/pl.json"
+  ( cd "$_paw" && HOME="$_PA/home" CLAUDE_PROJECT_DIR="$_paw" CREW_GATE_LOG=/dev/null bash "$HOOKS/guard-bash.sh" < "$_PA/pl.json" >"$_PA/out" 2>"$_PA/err" ); _par=$?; _pae="$(cat "$_PA/err")"; }
+_pa_wire(){ printf '%s' "$1" > "$_paw/.claude/settings.json"; }
+_PAW_ON='{"hooks":{"UserPromptSubmit":[{"hooks":[{"type":"command","command":"bash .claude/hooks/prompt-approval.sh"}]}]}}'
+_parow=""
+_pa_want(){  # $1 = label, $2 = text that must be there, $3 = text that must not
+  case "$_par/$_pae" in 2/*"$2"*) case "$_pae" in *"$3"*) _parow="$_parow [$1: says '$3']" ;; esac ;; *) _parow="$_parow [$1: rc $_par, no '$2']" ;; esac; }
+_pa_wire "$_PAW_ON"
+_pa_gate auto 'git commit -m x';          _pa_want 'wired, commit' 'write only this: approve: commit' 'APPROVAL PATH IS CLOSED'
+                                          _pa_want 'wired, commit, one block' 'in ONE code block' 'approve: push'
+_pa_gate dontAsk 'git push origin feat/x'; _pa_want 'wired, push' 'write only this: approve: push' 'APPROVAL PATH IS CLOSED'
+_pa_gate auto 'git commit -m x';          _pa_want 'wired, Turkish line' 'yalnız şunu yaz: onay: commit' 'APPROVAL PATH IS CLOSED'
+rm -f "$_paw/.claude/settings.json"
+_pa_gate auto 'git commit -m x';          _pa_want 'no settings' 'APPROVAL PATH IS CLOSED' 'write only this'
+                                          _pa_want 'no settings, the ways' 'Shift+Tab' 'ONE code block'
+_pa_wire '{"note":"prompt-approval.sh","hooks":{"UserPromptSubmit":[{"hooks":[{"type":"command","command":"bash .claude/hooks/route-hint.sh"}]}]}}'
+_pa_gate auto 'git push origin feat/x';   _pa_want 'named before the event only' 'APPROVAL PATH IS CLOSED' 'write only this'
+_pa_wire '{"hooks":{"PreToolUse":[{"hooks":[{"type":"command","command":"bash .claude/hooks/guard-bash.sh"}]}]}}'
+_pa_gate auto 'git commit -m x';          _pa_want 'other events only' 'APPROVAL PATH IS CLOSED' 'write only this'
+rm -f "$_paw/.claude/settings.json"; _pa_wire "$_PAW_ON"; mv "$_paw/.claude/settings.json" "$_paw/.claude/settings.local.json"
+_pa_gate auto 'git commit -m x';          _pa_want 'wired in settings.local.json' 'write only this: approve: commit' 'APPROVAL PATH IS CLOSED'
+rm -f "$_paw/.claude/settings.local.json"
+if [ -z "$_parow" ]; then pass "the auto-mode refusal asks in one shape when the approval hook is wired, and says the path is closed when it is not (9 readings, each refused)"
+else fail "the auto-mode refusal does not say what it should:$_parow"; fi
+# The wiring changes a sentence, never the verdict: with no settings at all, a record the hook wrote still allows
+# its command, and the same command without the record is refused.
+_pa_say auto 'approve: commit' >/dev/null; _pa_gate auto 'git commit -m x'; _pav1="$_par"
+_pa_new; _pa_gate auto 'git commit -m x'; _pav2="$_par"
+[ "$_pav1/$_pav2" = 0/2 ] && pass "the wiring check moves no verdict: a recorded approval is allowed (rc 0) and its absence refused (rc 2) with no settings file" \
+                          || fail "the wiring check moved a verdict: approved $_pav1 (want 0), unapproved $_pav2 (want 2)"
 fi   # prompt-approval.sh present
 
 # ---- the two definitions that live in two files, and the wiring -----------------------------------------------
@@ -9171,6 +9238,35 @@ if [ -n "$SGR" ] && [ -f "$SGR/.gitattributes" ] && [ -d "$SGR/packaging" ] && [
       [ "$(printf 'README.md\r\n' | bash "$CDO")" = docs ] || _cv="$_cv crlf"
       [ -z "$_cv" ] && pass "ci-docs-only.sh: documentation reads docs; a hook, evals/run.sh, kit/README.md, ci.yml or an empty diff reads code" \
                     || fail "ci-docs-only.sh gave the wrong verdict for:$_cv"
+      # The third answer, `text`: a pull request that changes only the text of skills, agents or commands skips the
+      # macOS and Windows jobs as a documentation one does, and still runs the Linux verify job. That list is pinned
+      # the same way, and every pattern must be a .md under one of the six text directories: `kit/*`, a script or
+      # kit/CLAUDE.md in it would let a gate change skip the platforms where it can break.
+      cdo_tpats(){ awk '/# TEXT-PATTERNS-START/{f=1;next} /# TEXT-PATTERNS-END/{f=0} f && /\) *return 0/ {sub(/^[[:space:]]*/,""); sub(/\).*/,""); print}' "$1"; }
+      cdo_tunsafe(){ while IFS= read -r _p; do case "$_p" in kit/skills/\*.md|kit/agents/\*.md|kit/commands/\*.md|plugin/skills/\*.md|plugin/agents/\*.md|plugin/commands/\*.md) ;; *) printf '%s\n' "$_p" ;; esac; done; }
+      _tp="$(cdo_tpats "$CDO" | tr '\n' ' ' | sed 's/ $//')"
+      _twant='kit/skills/*.md kit/agents/*.md kit/commands/*.md plugin/skills/*.md plugin/agents/*.md plugin/commands/*.md'
+      _ttu="$(printf '%s\n' 'kit/*' 'kit/hooks/*.md' 'kit/skills/*' 'kit/skills/*.md' | cdo_tunsafe | grep -c .)"
+      if [ "$_tp" != "$_twant" ]; then fail "the text-only list changed — it reads '$_tp', pinned '$_twant'. Widening it lets a change skip macOS and Windows; update this pin deliberately"
+      elif [ -n "$(cdo_tpats "$CDO" | cdo_tunsafe)" ]; then fail "a text-only pattern is not a .md under skills, agents or commands: $(cdo_tpats "$CDO" | cdo_tunsafe | tr '\n' ' ')"
+      elif [ "$_ttu" != 3 ]; then fail "the text-pattern check caught $_ttu of 3 planted patterns (kit/*, kit/hooks/*.md, kit/skills/*) — it reads nothing"
+      else pass "the text-only list is exactly the .md files of skills, agents and commands in kit/ and plugin/; 3 planted wider patterns are caught"; fi
+      _cv=""
+      [ "$(cdo kit/skills/x/SKILL.md plugin/skills/x/references/y.md)" = text ] || _cv="$_cv text-set"
+      [ "$(cdo kit/agents/a.md CHANGELOG.md README.md)" = text ]               || _cv="$_cv text+docs"
+      [ "$(cdo kit/skills/x/SKILL.md kit/hooks/guard-bash.sh)" = code ]        || _cv="$_cv text+hook"
+      [ "$(cdo kit/skills/x/scripts/run.sh)" = code ]                          || _cv="$_cv skill-script"
+      [ "$(cdo kit/skills/x/SKILL.md kit/CLAUDE.md)" = code ]                  || _cv="$_cv text+rulebook"
+      [ "$(cdo kit/skills/x/SKILL.md kit/hooks/trace-blocklist.txt)" = code ]  || _cv="$_cv text+blocklist"
+      [ "$(cdo README.md)" = docs ]                                            || _cv="$_cv docs-stays-docs"
+      [ -z "$_cv" ] && pass "ci-docs-only.sh: skill, agent and command text reads text, with documentation too; with a hook, a skill's script, kit/CLAUDE.md or a blocklist it reads code" \
+                    || fail "ci-docs-only.sh gave the wrong text verdict for:$_cv"
+      # The Linux verify job is gated on nothing: it holds the checks a text change can break.
+      _cyv="$(awk '/^  verify:$/{f=1;next} f && /^  [a-z-]+:$/{f=0} f' "$SGR/.github/workflows/ci.yml" | grep -cE '^    (if|needs):')"
+      _cyn="$(awk '/^  verify:$/{f=1;next} f && /^  [a-z-]+:$/{f=0} f' "$SGR/.github/workflows/ci.yml" | grep -c 'bash packaging/verify.sh')"
+      [ "$_cyv" = 0 ] && [ "$_cyn" -ge 1 ] \
+        && pass "ci.yml runs the Linux verify job on every pull request, a text-only one included (no if:, no needs:)" \
+        || fail "ci.yml's verify job is conditional ($_cyv if:/needs: line(s)) or was not found ($_cyn verify.sh call(s)): a text-only pull request would skip the budget, pointer, routing and plugin checks"
       # ...and ci.yml really uses it: both cross-platform jobs are gated on its answer, nothing else is.
       _cy="$SGR/.github/workflows/ci.yml"
       _gated="$(grep -c "if: needs.changes.outputs.scope == 'code'" "$_cy")"

package/kit/hooks/context-usage.sh

@@ -103,7 +103,7 @@ if [ -n "${IN:-}" ] && [ -n "${PSID:-}" ]; then
           # In auto and dontAsk the user's own message is the approval (hooks/prompt-approval.sh); plan and
           # bypassPermissions have no such route.
           case "$PM" in
-            auto|dontAsk) PMHOW="stage the change and show the message, then the user approves by sending a message that is only 'approve: commit' ('approve: push', 'approve: commit+push'; 'onay:' works too). It covers what is staged at that moment, for 30 minutes, until their next message; never write it for them" ;;
+            auto|dontAsk) PMHOW="stage the change, show the message in ONE code block and under it one line in the user's language, 'If you approve, write only this: approve: commit' ('approve: push', 'approve: commit+push'; 'onay:' works too); the user approves by sending that text alone. It covers what is staged at that moment, for 30 minutes, until their next message; never write it for them" ;;
             *)            PMHOW="a real yes still comes first, then the user switches mode (or exports CLAUDE_GIT_OK=1 in headless/CI)" ;;
           esac
           echo "🔒 Permission mode: $PM. git commit/push fail closed in this mode (§4.4). Only when a commit or push comes up: say so before you ask for approval; $PMHOW. Otherwise do not mention it."

package/kit/hooks/guard-bash.sh

@@ -2355,6 +2355,26 @@ _approval_ok(){  # 0 = the user's recorded approval covers THIS call. Otherwise
   [ -n "$tr" ] && [ "$cur" = "$tr" ] || { _APW="the commit on HEAD does not carry what the user approved"; return 1; }
   return 0
 }
+# IS THE RECORDING HOOK WIRED? Asked only when a commit or a push is about to be refused, so that the refusal names
+# a way that exists. It reads the settings this hook can see: the plugin's own hooks.json, the project's
+# settings.json and settings.local.json, the user's settings.json. HONEST SCOPE: the text of each file is searched
+# for the script's name after the event's name; it is not parsed, and managed settings are not read. A wrong answer
+# changes a sentence, never the verdict: the command is refused either way. eval/doctor.sh does the parsed check.
+_appr_wired(){  # 0 = prompt-approval.sh is beside this hook and a settings file wires it; else _APRW names what was read
+  local f t d="${CLAUDE_PROJECT_DIR:-.}" seen="" here="${BASH_SOURCE%/*}"
+  [ "$here" = "${BASH_SOURCE}" ] && here=.
+  d="${d//\\//}"; d="${d%/}"
+  _APRW="no prompt-approval.sh beside this hook"
+  [ -f "$here/prompt-approval.sh" ] || return 1
+  for f in "${CLAUDE_PLUGIN_ROOT:+${CLAUDE_PLUGIN_ROOT//\\//}/hooks/hooks.json}" "$d/.claude/settings.json" "$d/.claude/settings.local.json" "${HOME:+${HOME//\\//}/.claude/settings.json}"; do
+    [ -n "$f" ] && [ -f "$f" ] || continue
+    seen="$seen${seen:+, }$f"
+    t=""; IFS= read -r -d '' t < "$f" || true
+    case "$t" in *'"UserPromptSubmit"'*prompt-approval.sh*) return 0 ;; esac
+  done
+  _APRW="read: ${seen:-no settings file found}"
+  return 1
+}
 allow_approved(){
   gatelog ALLOW 4.4 "the user's own approval message covers this command"
   printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"%s"}}\n' \
@@ -3144,11 +3164,22 @@ ${BRANCH_WARN}Approve only if the commit message above was shown to you and you
       gatelog BLOCK 4.4 "commit/push with no matching approval from the user"
       echo "GUARD (§4.4): 'git commit/push' needs the user's approval, and in '$PERM_MODE' a permission prompt is answered by software, not by a person." >&2
       echo "Not allowed now: $_APW." >&2
-      echo "Present the commit MESSAGE to the user (stage first: the approval covers what is staged at that moment). Then one of:" >&2
-      echo "  (a) the user sends a message that is ONLY the approval: 'approve: commit', 'approve: push' or 'approve: commit+push' ('onay: …' works too)." >&2
-      echo "      It is tied to the staged diff and HEAD at that moment, lasts 30 minutes and ends at the user's next message. The command then runs ALONE in its call (no cd, no pipe, nothing chained): git commit -m …, or git push <remote> <branch>. OR" >&2
-      echo "  (b) the user presses Shift+Tab to switch to default/acceptEdits — in this session, no restart — and this gate asks them directly, OR" >&2
-      echo "  (c) the user runs the command in their own terminal." >&2
+      if ! _appr_wired; then
+        # The record is written by one hook. Where it is not wired, a message from the user records nothing, and
+        # telling them to type one sends them into a wall (measured in the field: a worktree on an older Crewforth).
+        echo "THE APPROVAL PATH IS CLOSED IN THIS SESSION: the hook that records the user's approval (prompt-approval.sh) is not wired on UserPromptSubmit in the settings in effect ($_APRW). A message 'approve: …' records nothing here." >&2
+        echo "Tell the user exactly that, in their language, and give them the two ways that work: Shift+Tab to default/acceptEdits (this gate then asks them directly), or the command in their own terminal." >&2
+        echo "Do not create an approval any other way." >&2
+        exit 2
+      fi
+      _aps=push; git_has "$CMD_SEEN" 'commit' && _aps=commit
+      echo "ASK THE USER NOW, in their language, in this shape and with nothing after it (stage first: the approval covers what is staged at that moment):" >&2
+      echo "  1. the commit message, whole, in ONE code block;" >&2
+      echo "  2. under it ONE line:  If you approve, write only this: approve: $_aps" >&2
+      echo "     (in Turkish:  Onaylıyorsan yalnız şunu yaz: onay: $_aps). Name the one that fits: commit, push, or commit+push when a push follows the commit." >&2
+      echo "Their reply has to be that text alone: a sentence such as 'go ahead and commit' is not an approval. It is tied to the staged tree and HEAD, lasts 30 minutes and ends at their next message." >&2
+      echo "Then run the command ALONE in its call (no cd, no pipe, nothing chained): git commit -m '…', or git push <remote> <branch>." >&2
+      echo "The other ways: Shift+Tab to default/acceptEdits (this gate then asks them directly), or the command in their own terminal." >&2
       echo "Only the user can write that message. Do not write it for them, and do not create an approval any other way." >&2
       exit 2 ;;
     *)

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

@@ -13,8 +13,8 @@ Otherwise do not use this skill: `frontend` and the project's own stack apply (s
 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); the depth and the sources are in
-`references/`. Not used in a project on another stack (delete it if needed).
+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
@@ -31,7 +31,8 @@ below was checked against Flutter's own documentation (docs.flutter.dev, dart.de
   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).
+  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
@@ -48,6 +49,11 @@ below was checked against Flutter's own documentation (docs.flutter.dev, dart.de
   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
@@ -66,23 +72,45 @@ below was checked against Flutter's own documentation (docs.flutter.dev, dart.de
 ## 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.
-- User-facing text goes through `gen-l10n` (ARB files, `AppLocalizations.of(context)`), plurals and placeholders in
-  ICU form — never concatenated. The `i18n-integrity` skill checks the files.
+- **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; generated and compared on the same
-  platform with fonts loaded first (`flutter test --update-goldens` refreshes them).
-- Every new screen gets a widget test at the narrowest and widest window the app supports, and the a11y guideline test.
+- **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).
 
@@ -90,5 +118,7 @@ below was checked against Flutter's own documentation (docs.flutter.dev, dart.de
 - `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; the narrowest and widest window are tested.
+- 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

@@ -4,7 +4,8 @@ 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).
+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.
@@ -32,6 +33,23 @@ documentation states them (2026-10-02).
 - 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
@@ -51,5 +69,13 @@ testWidgets('meets the accessibility guidelines', (tester) async {
 });
 ```
 
-Run it for every new screen, and run the screen's widget test at the narrowest and widest window the app supports
-(`tester.view.physicalSize` and `devicePixelRatio`, reset afterwards).
+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

@@ -33,6 +33,15 @@ https://dart.dev/tools/dart-format and https://dart.dev/tools/pub/private-files
   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`.
@@ -47,6 +56,9 @@ https://dart.dev/tools/dart-format and https://dart.dev/tools/pub/private-files
 - 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,
@@ -57,3 +69,32 @@ https://dart.dev/tools/dart-format and https://dart.dev/tools/pub/private-files
 - 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.