crewforth 3.0.3 → 3.1.0-rc.1

package/CHANGELOG.md

@@ -5,6 +5,217 @@ Crewforth was named Claude Starter Kit until 3.0.0.
 Notable changes to this project are recorded here. Format follows [Keep a Changelog](https://keepachangelog.com/en/),
 versioning follows [SemVer](https://semver.org/).
 
+## [Unreleased] — 3.1.0
+
+### Security
+
+- **A git subcommand the shell fills in walked past every gate.** Each rule about a git command finds it by its name,
+  and with an expansion inside the word the name is not in the text: `git com${z}mit`, `c=commit; git "$c"`, `git
+  $(printf com)mit`, a backtick, and the same for `git pu${z}sh --force`, `git re$(:)set --hard`, `git cl${z}ean -fdx`
+  and `git co${z}nfig core.hooksPath …`. Measured: 20 of 22 such calls passed silently, and git ran them. A git call
+  whose subcommand holds an expansion is refused now, in every session. In PowerShell, git started through
+  `System.Diagnostics.Process` (`[Diagnostics.Process]::Start('git','commit -n …')`, a `ProcessStartInfo`) is refused
+  as well: its arguments are one string no rule reads. An expansion anywhere else in a git call is untouched: of 4986
+  real commands that hold git, 2850 have one, none in the subcommand, and none changed its verdict.
+- **In PowerShell, a force push handed to git as arguments was not read.** `Start-Process git -ArgumentList
+  'push','--force',…` and `& $g push --force …` run the same git command as the plain form; of 23 such forms of
+  `push --force` (`-f`, `+ref`, `--force-with-lease`), `reset --hard`, `clean -f` and `core.hooksPath`, 21 passed. The
+  arguments are judged now as the git command they make, by the same rules that judge the plain form, and the refusal
+  says what was read.
+- **A `git commit` is read the way the shell and git read it.** The rules for `--no-verify`, `--amend` and a commit
+  that takes its content from the working tree looked for those words and walked the command token by token. Each of
+  these reached the approval prompt with no rule firing (and with `CLAUDE_GIT_OK` ran with nobody asked), measured by
+  running them: `git commit -n` and `--no-verif` skip the hooks; `--amen` amends; `-m x 2>&1 -a`, `-mxm b.txt`,
+  `-m 'a"' -a ; echo 'b"'` and `-F - <<END -a` commit the working tree; `cd ../other && git commit` and
+  `GIT_INDEX_FILE=… git commit` commit something the review record does not describe; `bash -c 'git commit -am x'`
+  hides the whole command. The command is now read left to right — quotes as the shell pairs them, here-document
+  bodies as data, redirections as redirections — and every `git commit` in it against git's own option table,
+  wherever it sits (braces, `if`, a wrapper, a quoted command word). Refused with the reason: an abbreviated or
+  unknown option, an argument the shell would expand into something else, a `-c` setting or a `GIT_` / `HOME`
+  variable that changes what git reads, and a commit after a `cd` into another repository. Nothing that was refused
+  before is let through.
+- **`core.hooksPath` could be switched off without `git config`.** `printf '[core]\n\thooksPath = /dev/null\n' >> .git/config`
+  passed, and after it a commit from your own terminal skipped the trace and secret scans. `.git/config` (a worktree's
+  and a submodule's too), your own `~/.gitconfig` and `~/.config/git/config`, and `.claude/git-shim` are gate files now: a shell write and the file tools are refused,
+  reading is not. `git config include.path`, `includeIf` and `GIT_CONFIG_` variables that carry `hooksPath` are
+  refused as well, and so is an abbreviated `--no-verify` on any git command.
+- **A large commit command could run past the gate's timeout, and a hook that times out does not block.** `guard-bash.sh`
+  stripped and padded the whole command with `${text//x/y}`, ten times over, and bash rebuilds the string for every
+  match: a 46 KB commit whose message is a quote-dense here-document took 335 s on macOS and 14 s at 18 KB on Windows,
+  against a 600 s timeout. The substitutions are done a piece at a time now; a 30 KB commit of that shape is judged in
+  about a second. Other shapes still cost the square of their size (a 64 KB commit took 154 s to read), so a command
+  that holds a `git commit` is read up to 32768 bytes and refused unread above, with the advice to put the message in
+  a file and use `git commit -F <file>`. And whatever the command, taking it out of the hook's JSON costs the square of
+  its size (256 KB of an escape-dense command: 49 s, 512 KB: 200 s), in `guard-bash.sh` and `guard-commit-scan.sh` alike,
+  so a Bash or PowerShell call above 262144 bytes is refused before it is parsed, by size alone, with the advice to put
+  the long content in a file. The largest of 12387 real commands is 31639 bytes. Write and Edit are not limited.
+- **A Write or Edit of a few megabytes ran `guard-write.sh` past its timeout, a gate file included.** The look for a
+  second path key walked the content with an expansion that costs the square of the size when nothing matches: 1 MB
+  took 24 s on macOS, and a 6 MB Write to `.claude/hooks/guard-bash.sh` was refused after 636 s, which is after the
+  600 s timeout, so it was not refused. The key search walks the payload a piece at a time now: the same Write is
+  refused in 2.6 s, and an ordinary 6 MB file passes in the same time. The file tools stay unlimited in size.
+- A review record could vouch for any staged diff once `git config diff.external true` was set: the staged diff then
+  prints nothing, and every change got the same id. The id is computed with `--no-ext-diff --no-textconv`.
+- A recursive forced delete of `.` or `..` passed in both shells (`rm -rf .`, `rm -rf ..`,
+  `Remove-Item -Recurse -Force .`): the rule looked for `/`, `*` or `~` in the target, and these carry none. They are
+  stopped now, in any flag spelling, with `sudo`, and across a backslash line break.
+- In PowerShell a path was a target only when it began with a drive letter, a UNC prefix or `$HOME`:
+  `Remove-Item -Recurse -Force src\app` and `"$env:TEMP\x"` passed, while `rm -rf src/app` was stopped. A target
+  with a path separator is stopped now, and so is a recursive forced removal fed by a pipeline.
+- **With no Git Bash, nothing guarded the session.** On Windows, when Claude Code finds no Git Bash, every Crewforth
+  gate fails to start (they are bash scripts; the failure does not block), and PowerShell is the only shell. One hook
+  now names no shell: Claude Code runs it through bash where there is one — it leaves at once, starting no process —
+  and through PowerShell where there is none, and there it stops every call of the Bash, PowerShell, Write, Edit and
+  NotebookEdit tools, with the `CLAUDE_CODE_GIT_BASH_PATH` to set. Reading and searching keep working.
+- Two spellings of `-Recurse` and `-Force` walked past the PowerShell delete rule, which wanted a hyphen and then
+  whitespace: a value after a colon (`-Recurse:$true -Force:$true`, `-Rec:1 -Fo:1`), and an en dash, an em dash or a
+  horizontal bar in place of the hyphen. PowerShell 5.1 deletes the tree with each of them (measured). They are
+  recognised now, whether the dash arrives as itself or as a JSON `\u` escape.
+
+### Added
+
+- **`frontend-flutter`: a stack layer for Flutter**, beside `frontend-rn-expo`. It applies only in a project whose
+  `pubspec.yaml` depends on the Flutter SDK, and `crew-frontend-expert` adds it on top of `frontend` there. It leaves
+  state management, routing and the lint set to the project, and holds what Flutter itself asks for: the layers and
+  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.
+- **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)
+  is recorded by a new hook, `prompt-approval.sh`, with what git reports at that moment: the tree of what is staged
+  and `HEAD` for a commit; `HEAD`, the branch, its remote and the address that remote pushes to for a push; and the
+  session you wrote in. The confirmation you see names that address. `guard-bash.sh` then allows one call and no other: `git commit -m …` alone (a single-quoted
+  message, or one read from a here-document with a quoted delimiter; `-q`, `-s`, `-v`), or
+  `git push <remote> <branch>` alone. A changed index, a moved `HEAD`, a second commit, another branch, remote or
+  address, a refspec, another option, a `cd`, a pipe or a second command is refused, with the reason. The record
+  lasts 30 minutes and your next message ends it. It opens neither the review-before-commit rule nor any destructive
+  command, and `plan` and `bypassPermissions` stay closed.
+  A session cannot produce the approval it would use: the file tools and any shell command that names the record
+  are refused, and so are a command that feeds the hook a payload of its own and, in those two modes, one that
+  starts a Claude Code session continuing this one. Those rules match names, as the rules for the gate files do.
+- **Studio: two more views of a session.** The **Timeline** draws the same agents against the clock, one row each,
+  with a drawer for an agent's last error; the **List** sorts them by what needs someone, and is the view a narrow
+  window opens on. `g`, `t` and `l` switch between Graph, Timeline and List. The time an agent waited for you is drawn
+  only for a session Studio started, and only since the panel started; for any other session the Timeline says
+  `Not measured: this session's approvals are not seen by Studio`.
+- **Studio: an approval dock.** A tool call in a session Studio started waits along the bottom of the panel,
+  whichever session and view are on screen, with the agent that asked, the tool and its input: Allow once, Allow the
+  tool for this session, or Deny (`a`, `s`, `d`); denied at 45 s when nobody answers. A session allowance is listed
+  in the inspector's Gates tab and can be revoked there.
+- **Studio: a New session panel.** The project, the permission mode and an optional first message. Plan is the
+  default; Accept edits and Default are the other two, and modes that skip Crewforth's gates are not offered.
+- **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.
+
+### Changed
+
+- **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.
+- **A command that names a gate file must be one that reads it.** The rule that guards the hooks, `settings.json`,
+  the rulebook and the git hooks looked for a write verb (`rm`, `mv`, `cp`, `tee`, …) in front of the path, and a
+  list of verbs is never complete: of 39 ways to write or delete a gate file, 32 passed (in 3.0.3 as well: `curl -o`,
+  `wget -O`, `sort -o`, `git log --output=`, `tar -C`, `unzip -d`, `unlink`, `shred`, `touch`, `patch`, an editor,
+  `find … -delete`, `git checkout <rev> -- <file>`). The question is turned round. A command that names a gate path
+  passes when it is a reader (`grep`, `cat`, `head`, `tail`, `wc`, `ls`, `less`, `diff`, `jq`, `sed` without `-i`,
+  `find` without `-delete` or `-exec`, …), a runner of a hook script (`bash .claude/hooks/<x>.sh`), `chmod +x` on
+  one, or a git command that only reads or stages (`status`, `log`, `diff`, `show`, `add`, `commit`, a `git config`
+  that reads); anything else is refused, with the reason. A path that is hidden is followed where the text allows
+  it: quoting inside the name, the `.claude` folder itself, a glob, a variable or a loop that holds the path, a `cd`
+  into the folder, a command substitution, `xargs`. `bash -c`, `eval`, `source`, a changed `PATH`, an alias or a
+  function in such a call, and an interpreter fed a here-document that names a gate file are refused.
+  **Reading is freer than before:** `grep -n rm .claude/hooks/guard-bash.sh` and `cat /Users/ed/p/.claude/hooks/x`
+  were refused for the word `rm` and the folder `ed`, and pass now. Bash tool; a PowerShell call keeps the verb
+  rule, without counting a verb that is a name in a path.
+- **A quoted argument is no longer read as a command.** `git commit -m "drop the rm -rf /tmp/build step"` deletes
+  nothing and `claude -p "… git push --force origin main"` pushes nothing, yet the §4.5 rules read the command as
+  text and refused both (measured: 14 of 20 such commands). The gate now takes the quoted argument out before those
+  rules read, for a short list of commands that do not run their argument: `git commit` / `git tag -m`, `gh pr|issue|release
+  --title` / `--body`, `claude -p`, the grep family, and `echo` / `printf` when the call has no pipe and no
+  redirection. A `claude -p` prompt is taken out only when nothing in the call changes the directory (`cd`, `pushd`,
+  `popd`, `git -C`) and its other options are `--output-format`, `--model` or `--max-turns`: the session it starts is
+  judged by the gates of where it starts and with the settings it is given. The
+  word must be wholly quoted, and a double-quoted one must hold no `$(` and no backtick. Everything else is as
+  before: the same words outside the quotes, after the argument, printed into a shell or a file, handed to `bash
+  -c`, `eval`, `ssh` or `xargs`, stored with `printf -v`, or anywhere in a call that changes what a command word
+  means (`alias`, `hash`, a function, `PATH=`) are refused. Bash tool only.
+- **Trusting or declining a component is confirmed.** `skill-trust.sh --trust-one` and `--decline-one` printed nothing
+  on success, and in the field a session that had just declined a skill said it had not checked the record. Each
+  prints one line now (the component, the file, the first characters of the digest it holds), and only after the
+  line is read back from the file; when the answer could not be written the command exits 1 and says so.
+- **Reading `core.hooksPath` is no longer refused on Windows.** `git config --get core.hooksPath` is how a person
+  checks that the gate is armed, and a read is let through only when the payload holds no escape the reader drops.
+  That was asked of the whole payload, and a Windows `cwd` is full of them once JSON-encoded (`C:\\repos\\app` holds
+  a backslash and an r), so in such a directory every read was refused as tampering. It is asked of the command
+  now, with every escaped backslash taken out first. Of 250 measured cells (7 reads, 18 writes, a POSIX `cwd` and
+  four Windows ones, Bash and PowerShell) 40 reads changed from refused to passed; every write, a real CR, form
+  feed or backspace escape in the command among them, is refused as before.
+- **A project's own hook chain survives the second update.** The first run puts `.claude/git-shim` in front of it
+  and points git there; the second read that as "no chain" and pointed git at `.claude/hooks`, so the project's own
+  `pre-commit` never ran again, with nothing said (a project with `.husky` was found again, as `.husky` and not the
+  `.husky/_` it had). The chain is read back from the shim.
+- **The doctor knows `.claude/git-shim`.** On a project with hooks of its own it answered "not Crewforth's hooks" and
+  advised `git config core.hooksPath .claude/hooks`, the command that disconnects the project's hooks. A shim that
+  runs Crewforth's hook is healthy; where a chain of the project's own exists the advice is the update, which
+  keeps it.
+- **The session is told when the git hooks are not connected.** An install made before `git init`, and every clone
+  of a repository that shares `.claude/`, starts with `core.hooksPath` unset: a commit typed in a terminal is then
+  scanned by nothing. Crewforth does not change git's configuration by itself; the session start says so, and the
+  fix stays the user's.
+- **The doctor's Git Bash advice ends with "close the terminal and Claude Code and open them again".** An open
+  terminal keeps the old value of `CLAUDE_CODE_GIT_BASH_PATH`; in the field the fix was right and the proof came two
+  rounds late.
+- **The doctor reads §4.2's list.** `trace-blocklist.txt` ships the vendor section as a commented placeholder, and
+  until a name stands there that rule looks for nothing: the doctor says so, as information. The placeholder made
+  active as it shipped is a warning.
+- **An update no longer loses an edit of the three files Crewforth owns.** `adopt` and `update` rewrote
+  `.claude/AGENT_TEMPLATE.md` and `.claude/DISCIPLINE.md` on every run with no look at what was there, so a copy the
+  user had edited was gone without a word (`README.md` was already kept when it differed). One rule for the three now:
+  a copy that is this version's, or exactly what an earlier release shipped (line endings aside), is refreshed and
+  nothing is kept; anything else goes to `.claude/.legacy-backup/<time>/` first, and the update names it. What "an
+  earlier release shipped" is comes from `kit/owned-blobs.tsv`, generated from the release tags: 6 versions of
+  AGENT_TEMPLATE.md, 8 of README.md and 24 of DISCIPLINE.md, so an untouched copy from any of them does not pile up
+  in the backup directory on each update. A copy that cannot be backed up is left as it is.
+- **A gate that times out does not block, so the gates got faster and their timeout longer.** Claude Code runs the
+  tool call when a `PreToolUse` hook reaches its timeout; one field session on 3.0.0 showed nine such calls in a day.
+  - Every read-only Bash call, every Write and Edit, and every PowerShell call now costs **no process at all** in the
+    four gates (it was 5 in `guard-bash.sh`, 7 in `guard-commit-scan.sh` and 4 in `guard-write.sh`, counting the
+    `$( )` subshells the 3.0.1 count did not see). On Git Bash a process costs 62–135 ms, and seconds on a loaded
+    machine.
+  - The four gates' timeout is 600 s, Claude Code's own default; Crewforth had set 60. The other hooks keep 60.
+- **Studio has a new interface.** The graph is a left-to-right tree: the session on the left, its agents to the right,
+  a workflow run as one group, and a strip above the canvas naming what needs attention. Selecting an agent opens an
+  inspector with four tabs (Overview, Conversation, Gates, Stats), and the inspector, the conversation and the New
+  session panel share one place on the right.
+- **Allow in Studio is an explicit answer to Claude Code.** In the Accept edits and Default modes the approval hook
+  returns `permissionDecision: allow`; before, it only stayed silent, and Claude Code then refused a write in Default
+  mode (measured on Windows). In Plan it still says nothing. A Crewforth gate or a `deny` rule refuses the call all
+  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.
+
+## [3.0.4] — 2026-10-05
+
+### Security
+
+- **A command continued on the next line is read as one command.** A backslash at the end of a line continues it, and
+  the gates read each line on its own: `rm -f \` + newline + `.claude/hooks/guard-bash.sh` deleted a gate file, `rm \`
+  + newline + `-rf …`, `git push \` + newline + `--force` and `curl … \` + newline + `| bash` were not refused, and
+  `git \` + newline + `push` or `commit` reached neither the approval prompt nor the review gate, nor the commit
+  content scan (measured on 3.0.3, macOS and Windows). The command is now joined before anything reads it, the way
+  the shell joins it: an odd number of backslashes continues the line, a PowerShell call continues with a backtick,
+  and a line that may be a comment is read both ways.
+- **A gate path spelled with backslashes is the gate path.** In a PowerShell call `Remove-Item
+  .claude\hooks\guard-bash.sh` and `Set-Content .claude\settings.json …` were not recognised and passed.
+- **A gate that stops on an error of its own refuses the call.** Claude Code blocks a tool call on exit 2 only, so a
+  hook that died with status 1, or went on past the rule that broke and left with 0, had allowed the call. Each
+  PreToolUse gate (`guard-bash.sh`, `guard-commit-scan.sh`, `guard-write.sh`, `guard-powershell.sh`) now answers 2,
+  and says the error was its own, when it leaves with a status that is neither 0 nor 2 and when a command of it is
+  abandoned in the middle. Not covered: an error inside a command substitution, and a command that is not found.
+
 ## [3.0.3] — 2026-10-03
 
 ### Security

package/README.md

@@ -1,6 +1,6 @@
 <p align="center"><img src="https://raw.githubusercontent.com/Crewforth/crewforth/main/assets/logo.svg" alt="Crewforth" width="420"></p>
 
-**Crewforth is your engineering crew for Claude Code.** It adds subagents, skills, commands and hooks to Claude Code: 12 specialist agents that each own a domain, 39 skills that hold the method, 10 commands you start with `/crew-…`, and hooks that enforce the rules that matter.
+**Crewforth is your engineering crew for Claude Code.** It adds subagents, skills, commands and hooks to Claude Code: 12 specialist agents that each own a domain, 40 skills that hold the method, 10 commands you start with `/crew-…`, and hooks that enforce the rules that matter.
 
 ```bash
 npx crewforth init              # set up a new project
@@ -9,7 +9,7 @@ npx crewforth add <agent|skill> # copy one agent or skill into ./.claude
 npx crewforth studio            # open the Studio panel; installs nothing
 ```
 
-Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash and git; on Windows, use Git Bash (the gates run only when Claude Code finds it; `/crew-doctor` says when it does not).
+Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash and git; on Windows, use Git Bash (the gates run only when Claude Code finds it; when it does not, the tools that write or run commands are stopped and `/crew-doctor` names the path to set).
 
 [![npm](https://img.shields.io/npm/v/crewforth?style=flat-square&color=6D28D9)](https://www.npmjs.com/package/crewforth)
 [![License](https://img.shields.io/badge/license-MIT-5c6472?style=flat-square)](https://github.com/Crewforth/crewforth/blob/main/LICENSE)
@@ -29,7 +29,7 @@ Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash
 ## What you get
 
 - **12 specialist agents**, from `crew-planner` to `crew-commit-agent`, each owning one domain.
-- **39 skills** holding the method: testing, migrations, API contracts, observability, accessibility, deployment.
+- **40 skills** holding the method: testing, migrations, API contracts, observability, accessibility, deployment.
 - **10 commands**, each started with its `/crew-…` name: `/crew-plan`, `/crew-review`, `/crew-ship`, `/crew-handoff`, `/crew-brainstorm`, `/crew-update`, `/crew-doctor`, `/crew-gates`, `/crew-skill`, `/crew-studio`.
 - **Safe adoption.** `adopt` lands everything on a branch, staged and uncommitted; `main` is never touched.
 

package/VERSION

@@ -1 +1 @@
-3.0.3
+3.1.0

package/adopt.sh

@@ -220,9 +220,10 @@ _mt() {   # $1 = English text (the key); further args fill %s; result in _M
       ".NET pattern skill renamed: devarch-module -> cqrs-aop-module (content kept)") s=".NET desen skill'inin adı değişti: devarch-module -> cqrs-aop-module (içerik korundu)" ;;
       "⚠️  both devarch-module and cqrs-aop-module are present — nothing moved; remove the old one when ready") s='⚠️  devarch-module ve cqrs-aop-module ikisi birden var — hiçbir şey taşınmadı; hazır olduğunuzda eskisini silin' ;;
       "AGENT_TEMPLATE.md written (owned by Crewforth; refreshed on every update)") s="AGENT_TEMPLATE.md yazıldı (Crewforth'un dosyası; her güncellemede yenilenir)" ;;
-      "README.md differed from this version's — the old one is kept in %s/README.md") s="README.md bu sürümünkinden farklıydı — eskisi %s/README.md içinde saklandı" ;;
+      '%s is not a copy Crewforth shipped before this version — it is kept in %s/%s') s="%s, Crewforth'un bu sürümden önce gönderdiği bir kopya değil — %s/%s içinde saklandı" ;;
+      '%s could not be checked against what Crewforth shipped (git or the shipped list is missing) — the old copy is kept in %s/%s') s="%s, Crewforth'un gönderdikleriyle karşılaştırılamadı (git ya da gönderilen liste yok) — eski kopya %s/%s içinde saklandı" ;;
       'README.md refreshed (describes this version of Crewforth)') s="README.md yenilendi (Crewforth'un bu sürümünü anlatıyor)" ;;
-      "README.md differs from this version's and could not be backed up — left as it is") s='README.md bu sürümünkinden farklı ve yedeklenemedi — olduğu gibi bırakıldı' ;;
+      '%s is not a copy Crewforth shipped before this version and could not be backed up — left as it is') s="%s, Crewforth'un bu sürümden önce gönderdiği bir kopya değil ve yedeklenemedi — olduğu gibi bırakıldı" ;;
       "pre-2.0 install (profile=%s): profile pruning was removed — completing the install") s='2.0 öncesi kurulum (profile=%s): profil budama kalktı — eksikler tamamlanıyor' ;;
       "pre-2.0 install (profile=%s): nothing was missing — the full set was already present") s='2.0 öncesi kurulum (profile=%s): eksik yok — tam set zaten kuruluydu' ;;
       "overlap: %s -> skill '%s' already present (kept); original re-backed up") s="çakışma: %s -> '%s' skill'i zaten var (korundu); orijinal yeniden yedeklendi" ;;
@@ -523,11 +524,29 @@ fi
 rowm 'git' "$GITKIND"   # every GITKIND value is a literal with its own table row
 
 # existing hook system (decision #5 — single-hooksPath clash with husky/lefthook)
-HOOKSYS="none"
+HOOKSYS="none"; SHIM_CHAIN=""
 CURHP="$(git config --get core.hooksPath 2>/dev/null || true)"
 case "$CURHP" in
   "") : ;;
-  .claude/hooks|.claude/git-shim) HOOKSYS="Crewforth (already armed)"; CURHP="" ;;   # kit's OWN path — not a foreign chain (re-adopt must not shim itself)
+  .claude/hooks) HOOKSYS="Crewforth (already armed)"; CURHP="" ;;   # kit's OWN path — not a foreign chain (re-adopt must not shim itself)
+  .claude/git-shim)
+    # Crewforth's shim, from an earlier run: git is pointed at it, and IT holds the project's own chain. That chain
+    # is read back from the shim, or the next lines would see "no chain" and point git straight at .claude/hooks:
+    # measured, the second update of a project with core.hooksPath=myhooks left its own pre-commit never running
+    # again, with nothing said. (A project with .husky was found again by its directory; one with any other
+    # directory was not.)
+    HOOKSYS="Crewforth (already armed)"; CURHP=""
+    for _sf in .claude/git-shim/pre-commit .claude/git-shim/commit-msg; do
+      [ -f "$_sf" ] || continue
+      while IFS= read -r _sl || [ -n "$_sl" ]; do
+        _sl="${_sl%$'\r'}"
+        case "$_sl" in 'P="'*'/$H"') _sl="${_sl#P=\"}"; _sl="${_sl%/\$H\"}"; _sl="${_sl#\$ROOT/}"
+          case "$_sl" in ''|.claude/hooks|.claude/git-shim) ;; *) SHIM_CHAIN="$_sl" ;; esac ;;
+        esac
+      done < "$_sf"
+      [ -n "$SHIM_CHAIN" ] && break
+    done
+    [ -n "$SHIM_CHAIN" ] && HOOKSYS="core.hooksPath=$SHIM_CHAIN" ;;
   *) HOOKSYS="core.hooksPath=$CURHP" ;;
 esac
 [ -d .husky ] && HOOKSYS="husky (.husky/)"
@@ -1164,36 +1183,66 @@ copy_noclobber "$SRC/studio"   .claude/studio   "$KIT_PRESENT"; T_ADD=$ret_add;
 # lives in packaging/studio-test/, outside the payload, so nothing has to be deleted here and
 # the count is simply what landed.
 chmod +x .claude/studio/server/hooks/*.sh 2>/dev/null || true
-# AGENT_TEMPLATE.md — a kit-owned flat file, so it is written on every run rather than never-overwritten.
-# `/crew-skill` opens with `Read .claude/AGENT_TEMPLATE.md`, and until now only start.sh copied it
-# (start.sh:486). That left the command pointing at a file that does not exist on an adopted install, and
-# `update` is an alias of this script (bin/cli.js:48), so a copy placed by start.sh was never refreshed
-# either — it went stale from the day it landed and nothing ever noticed, because §3b iterates skills and
-# agents and this is neither. Overwriting is right for the same reason DISCIPLINE.md is overwritten: the
-# file states the kit's own contract, a project does not author it, and a stale contract is worse than none.
-cp "$SRC/AGENT_TEMPLATE.md" .claude/ 2>/dev/null && say 'AGENT_TEMPLATE.md written (owned by Crewforth; refreshed on every update)'
-# README.md — Crewforth's description of what lives under .claude/. start.sh copied it; this script never did, so an
-# updated project kept the README of the version it was first installed with (RC-1 field: both projects still
-# described 3.0.0). It is refreshed on every run now, and never at the cost of an edit: a copy that differs from this
-# version's (line endings aside) is kept first in .claude/.legacy-backup/<time>/README.md and named.
-if [ -f "$SRC/README.md" ]; then
-  if [ -f .claude/README.md ] && ! cmp -s "$SRC/README.md" .claude/README.md \
-     && ! tr -d '\r' < .claude/README.md 2>/dev/null | cmp -s "$SRC/README.md" -; then
-    _rbk="$LEG_BK"
-    if [ -z "$_rbk" ] || [ ! -d "$_rbk" ]; then
-      _rbk=".claude/.legacy-backup/$(date +%Y%m%d-%H%M%S)"; _b="$_rbk"; i=2
-      while [ -e "$_b" ]; do _b="$_rbk-$i"; i=$((i+1)); done; _rbk="$_b"
-    fi
-    if mkdir -p "$_rbk" 2>/dev/null && cp .claude/README.md "$_rbk/README.md" 2>/dev/null; then
-      [ -f .claude/.legacy-backup/.gitignore ] || printf '*\n' > .claude/.legacy-backup/.gitignore 2>/dev/null
-      say "README.md differed from this version's — the old one is kept in %s/README.md" "$_rbk"
-      cp "$SRC/README.md" .claude/ 2>/dev/null && say 'README.md refreshed (describes this version of Crewforth)'
-    else
-      warnm "README.md differs from this version's and could not be backed up — left as it is"
+# THE FLAT FILES CREWFORTH OWNS — AGENT_TEMPLATE.md, README.md and (in stage 3) DISCIPLINE.md. Each states the kit's own
+# contract, so it is rewritten on every run: `/crew-skill` opens with `Read .claude/AGENT_TEMPLATE.md`, the README
+# describes this version, and a stale discipline is worse than none. Until 3.1 two of the three were rewritten with
+# no look at what was there, so a copy the user had edited was lost without a word. One rule for the three now:
+#   * the same as this version's (line endings aside): written, nothing said about the old one;
+#   * a copy an earlier release shipped, untouched — its bytes, or its bytes with CR removed, are an id
+#     kit/owned-blobs.tsv holds for that file: refreshed, nothing kept (it is in the release it came from);
+#   * anything else is kept first in .claude/.legacy-backup/<time>/ and named, then refreshed: an edit of the user's,
+#     or a copy from a release the list does not hold (it holds the final releases below this VERSION, so a patch
+#     release made after this one, or a release candidate, is not in it). The line says what is known — "not a copy
+#     Crewforth shipped before this version" — and not that somebody edited it. When git or the list is missing
+#     nothing can be told, and the copy is kept the same way.
+# A copy that cannot be backed up is left as it is.
+_owned_bkdir(){  # -> LEG_BK: this run's backup directory (the legacy sweep's when it made one), created; 1 when it cannot be
+  local b i=2
+  if [ -z "$LEG_BK" ] || [ ! -d "$LEG_BK" ]; then
+    LEG_BK=".claude/.legacy-backup/$(date +%Y%m%d-%H%M%S)"; b="$LEG_BK"
+    while [ -e "$b" ]; do b="$LEG_BK-$i"; i=$((i+1)); done; LEG_BK="$b"
+  fi
+  mkdir -p "$LEG_BK" 2>/dev/null || return 1
+  # A team that shares .claude/ should not commit the backup by accident.
+  [ -f .claude/.legacy-backup/.gitignore ] || printf '*\n' > .claude/.legacy-backup/.gitignore 2>/dev/null
+  return 0
+}
+_owned_shipped(){  # $1 = name -> 0 when .claude/<name> is a copy an earlier release shipped · 1 it is not · 2 cannot tell
+  local f=".claude/$1" lst="$SRC/owned-blobs.tsv" h hl cr crl
+  [ -f "$lst" ] && command -v git >/dev/null 2>&1 || return 2
+  h="$(git hash-object --no-filters -- "$f" 2>/dev/null)" || return 2
+  [ -n "$h" ] || return 2
+  hl="$h"
+  # CR is stripped only when every CR ends a line (a Windows editor, an autocrlf copy); no shipped copy holds one.
+  # Whether there is a CR at all is asked with tr, not `grep -q`: Git for Windows' grep 3.0 answers "no" to
+  # `grep -q $'\r'` on a CRLF file (measured there: rc 1 on a file where `grep -c` counts 107), and an untouched copy
+  # checked out with core.autocrlf=true was then kept as if it had been edited.
+  cr="$(tr -dc '\r' < "$f" 2>/dev/null | wc -c | tr -d ' ')"
+  if [ "${cr:-0}" != 0 ]; then
+    crl="$(grep -c $'\r$' "$f" 2>/dev/null)"
+    [ "$cr" = "${crl:-x}" ] && hl="$(tr -d '\r' < "$f" 2>/dev/null | git hash-object --no-filters --stdin 2>/dev/null)"
+  fi
+  awk -F'\t' -v p="$f" -v a="$h" -v b="${hl:-$h}" '!/^#/ && $1 == p && ($2 == a || $2 == b) { f = 1 } END { exit !f }' "$lst"
+}
+_owned_refresh(){  # $1 = name under .claude/, $2 = a file holding this version's content -> 0 written · 1 left as it is
+  local n="$1" new="$2" cur=".claude/$1" rc
+  if [ -f "$cur" ] && ! cmp -s "$new" "$cur" && ! tr -d '\r' < "$cur" 2>/dev/null | cmp -s "$new" -; then
+    _owned_shipped "$n"; rc=$?
+    if [ "$rc" != 0 ]; then
+      if _owned_bkdir && cp "$cur" "$LEG_BK/$n" 2>/dev/null; then
+        if [ "$rc" = 2 ]; then say '%s could not be checked against what Crewforth shipped (git or the shipped list is missing) — the old copy is kept in %s/%s' "$n" "$LEG_BK" "$n"
+        else say '%s is not a copy Crewforth shipped before this version — it is kept in %s/%s' "$n" "$LEG_BK" "$n"; fi
+      else
+        warnm '%s is not a copy Crewforth shipped before this version and could not be backed up — left as it is' "$n"
+        return 1
+      fi
     fi
-  else
-    cp "$SRC/README.md" .claude/ 2>/dev/null
   fi
+  cp "$new" "$cur" 2>/dev/null
+}
+_owned_refresh AGENT_TEMPLATE.md "$SRC/AGENT_TEMPLATE.md" && say 'AGENT_TEMPLATE.md written (owned by Crewforth; refreshed on every update)'
+if [ -f "$SRC/README.md" ]; then
+  _owned_refresh README.md "$SRC/README.md" && say 'README.md refreshed (describes this version of Crewforth)'
 fi
 # Report the migration by what LANDED, not by what was missing: a component the payload lists can still be kept
 # out (EXCL_S), and must not be announced as restored when it was.
@@ -1482,8 +1531,10 @@ h1m "Stage 3 — activate the Crewforth discipline (without touching the project
 #     everything above the sentinel line. Contains NO @import (leaf) -> no 4-hop trap.
 if [ -f "$SRC/CLAUDE.md" ]; then
   kit_require_sentinel "$SRC/CLAUDE.md"
-  kit_discipline_of "$SRC/CLAUDE.md" > .claude/DISCIPLINE.md
-  say 'DISCIPLINE.md written (Crewforth discipline only; the project template stays out of it)'
+  kit_discipline_of "$SRC/CLAUDE.md" > .claude/DISCIPLINE.md.crew-new
+  _owned_refresh DISCIPLINE.md .claude/DISCIPLINE.md.crew-new \
+    && say 'DISCIPLINE.md written (Crewforth discipline only; the project template stays out of it)'
+  rm -f .claude/DISCIPLINE.md.crew-new
 fi
 
 # 3b) single-line @import into the project CLAUDE.md (if present DON'T touch content, only prepend; if absent create).
@@ -1578,6 +1629,7 @@ h1m 'Stage 4 — arm the git gates (SHIM via husky) + PROOF'
 # 4a) location of the existing hook chain (the shim calls this too)
 ORIG_HOOKS=""
 if [ -n "$CURHP" ]; then ORIG_HOOKS="$CURHP"
+elif [ -n "$SHIM_CHAIN" ]; then ORIG_HOOKS="$SHIM_CHAIN"   # the chain the shim of an earlier run already runs
 elif [ -d .husky ]; then ORIG_HOOKS=".husky"
 elif [ -x .git/hooks/pre-commit ] || [ -x .git/hooks/commit-msg ]; then ORIG_HOOKS=".git/hooks"; fi
 # never shim the kit onto its OWN hooks (re-adopt) — the shim would exec itself and recurse on every commit

package/kit/CLAUDE.md

@@ -170,7 +170,7 @@ a team that adopted Crewforth may have chosen to share them instead, and the tra
 No `git commit` / `git push` unless the user says "commit" / "push". `git add` and new branches: no approval, any
 mode (`add -f` is §4.5). "Done / we can proceed" is **not** approval. **Present the message FIRST** — even in
 auto/fast mode. `guard-bash.sh` asks in `default`/`acceptEdits`; in `auto`, `dontAsk`, `plan`, `bypassPermissions`
-nobody sees a prompt, so commit/push FAIL CLOSED — get a real yes, then switch mode. Never hand the user a command
+nobody sees a prompt, so commit/push FAIL CLOSED: get a real yes; the guard says how. Never hand the user a command
 to paste. **Headless/CI:** if `printenv CLAUDE_GIT_OK` is set AND this request itself says "commit"/"push", that IS
 the approval — commit (a review blocker still stops you) and show the message in your report.
 

package/kit/README.md

@@ -36,7 +36,7 @@ summarizes what lives under `.claude/` and how it works.
   comes back. Silent when nothing is new, and silent without a `kit-manifest.txt` rather than guessing.
 - **settings.json** — permissions and the hook chain (PreToolUse · UserPromptSubmit · Stop · SessionStart).
 - **`DISCIPLINE.md`** — behavior, four principles, workflow, definition of done, token discipline, and prohibitions.
-  Crewforth-owned: an update **overwrites** it, so keep nothing of your own here. Your `./CLAUDE.md` pulls it in with a
+  Crewforth-owned: an update **refreshes** it, so keep nothing of your own here (a copy you edited is kept in `.claude/.legacy-backup/` first, and named). Your `./CLAUDE.md` pulls it in with a
   single `@.claude/DISCIPLINE.md` line and holds your project rules, which win on conflict; in DISCIPLINE.md §4 they can only tighten, never loosen (its §4.1 names the one exception).
 - **`kit.conf`** — which installer ran and at what version. `stack=` is always `generic` since 3.0 (kept for older
   updaters); the project's stack itself lives in the `## Stack` section of `./CLAUDE.md`.

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

@@ -86,9 +86,13 @@ On a mixed/non-atomic diff, **propose a split**; do not commit before approval (
   proceed" is not approval (§4.4).
   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. Under `bypassPermissions`
-  the gate fails closed; there the user must switch modes or pre-authorise with `CLAUDE_GIT_OK=1` (which never
-  substitutes for approval).
+  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.
+  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
+  `CLAUDE_GIT_OK=1` (which never substitutes for approval).
 - **No AI trace:** the message contains no co-author trailer, auto-generation footer, robot emoji, AI-assistant/tool name,
   or the `.claude` name; the message is human, technical prose (§4.1).
 - **No vendor name:** the third-party template name and any "cleanup/vendor copy" disclosure are not written into the message (§4.2).

package/kit/agents/crew-frontend-expert.md

@@ -3,14 +3,14 @@ name: crew-frontend-expert
 color: purple
 description: |
   Stack-agnostic frontend expert — web, mobile (native, Flutter, React Native, MAUI, KMP), desktop.
-  The "how" lives in the `frontend` skill (an RN/Expo project adds `frontend-rn-expo`). **Use proactively — owns everything the user sees or
+  The "how" lives in the `frontend` skill (RN/Expo adds `frontend-rn-expo`, Flutter `frontend-flutter`). **Use proactively — owns everything the user sees or
   interacts with:** screens, components, navigation, client state, i18n, accessibility, responsive, native
   bridges, and all visual work — design systems, token/theme layers, typography, dark mode, "it doesn't look
   premium". Any request about it is yours whatever its size, wording or language.
 tools: Read, Grep, Glob, Edit, Write, Bash, PowerShell
 metadata:
   stage: produce
-  skills: [a11y, confidence-check, dependency-audit, frontend, frontend-design, frontend-rn-expo, i18n-integrity, observability, performance]
+  skills: [a11y, confidence-check, dependency-audit, frontend, frontend-design, frontend-flutter, frontend-rn-expo, i18n-integrity, observability, performance]
 ---
 
 # Frontend Expert (stack-agnostic)
@@ -48,8 +48,8 @@ On UI, component/page, navigation/routing, state, i18n interface, responsive, or
 
 ## How (applies the `frontend` skill + stack-specific layer)
 1. **Generic discipline:** the **`frontend`** skill applies on every stack — architecture, state, state-complete UI, i18n, a11y, performance.
-2. **Detect the stack:** `package.json` + repo structure → web (React/Next/Vue/Svelte/Angular), mobile (React Native/Flutter), desktop.
-3. **Stack-specific layer:** apply that stack's frontend skill. Ready example in Crewforth: **`frontend-rn-expo`** for mobile RN+Expo (optional). For a web/desktop project, the project's own frontend skill / CLAUDE.md.
+2. **Detect the stack:** `package.json` / `pubspec.yaml` + repo structure → web (React/Next/Vue/Svelte/Angular), mobile (React Native/Flutter), desktop.
+3. **Stack-specific layer:** apply that stack's frontend skill. Ready in Crewforth: **`frontend-rn-expo`** for mobile RN+Expo and **`frontend-flutter`** for Flutter (both optional, neither a default). For a web/desktop project, the project's own frontend skill / CLAUDE.md.
 4. **Also apply:** `frontend-design` (visual/UX quality — hierarchy, spacing, type, states) · `a11y` (accessibility gate) · `i18n-integrity` (translation integrity) · `observability` (client log/error) · `performance` (render/bundle) · `dependency-audit` (packages).
 
 ## DoD

package/kit/agents/crew-performance-expert.md

@@ -47,7 +47,7 @@ Static reading is legitimate for finding *where to point the measurement*:
 - **Allocation**: per-item allocation in a loop, a large buffer copied instead of streamed, string building in a loop.
 - **Payload/cache**: an oversized response, no caching where the input is stable, a cache keyed so it never hits.
 - **Client/render**: a re-render loop, work in a render path, an effect that re-triggers itself, an unbounded list
-  without virtualisation, a heavy import on the startup path ([[frontend]], [[frontend-rn-expo]]).
+  without virtualisation, a heavy import on the startup path ([[frontend]], [[frontend-rn-expo]], [[frontend-flutter]]).
 - **Startup**: work at module load that belongs behind first use.
 
 ## How

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

@@ -58,7 +58,7 @@ refuses a commit without it (§4.6). Use exactly this recipe; the hook hashes th
 ```bash
 # CREW-REVIEW-PASS (kept identical in guard-bash.sh; smoke-test pins the pair)
 mkdir -p .claude
-D=$(git diff --cached | git hash-object --stdin)
+D=$(git diff --cached --no-ext-diff --no-textconv | git hash-object --stdin)
 H=$(git rev-parse --verify --quiet HEAD 2>/dev/null || echo NONE)
 printf '{"diff_oid":"%s","head":"%s","ts":"%s"}\n' "$D" "$H" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .claude/review-pass.json
 ```

package/kit/eval/doctor.sh

@@ -78,6 +78,14 @@ _mt() {
       'core.hooksPath -> %s (commit-time gates active)') s='core.hooksPath -> %s (commit anındaki kapılar devrede)' ;;
       'core.hooksPath is unset — commit trace/secret/bloat gates are INACTIVE') s='core.hooksPath ayarlı değil — commit iz, gizli bilgi ve şişkinlik kapıları DEVRE DIŞI' ;;
       "core.hooksPath -> %s (not Crewforth's hooks)") s="core.hooksPath -> %s (Crewforth'un hook'ları değil)" ;;
+      "core.hooksPath -> %s (Crewforth's hooks run first, then the project's own — commit-time gates active)") s="core.hooksPath -> %s (önce Crewforth'un hook'ları, sonra projenin kendi hook'ları çalışır — commit anındaki kapılar devrede)" ;;
+      "core.hooksPath -> %s, but the shim there does not run Crewforth's hook:%s") s="core.hooksPath -> %s, ama oradaki shim Crewforth'un hook'unu çalıştırmıyor:%s" ;;
+      'update Crewforth (npx crewforth update), which writes the shim again') s="Crewforth'u güncelleyin (npx crewforth update); güncelleme shim'i yeniden yazar" ;;
+      "update Crewforth (npx crewforth update): this project has hooks of its own, and the update runs Crewforth's before them instead of replacing them") s="Crewforth'u güncelleyin (npx crewforth update): bu projenin kendi hook'ları var; güncelleme Crewforth'unkileri onların yerine koymaz, önlerinde çalıştırır" ;;
+      "update Crewforth (npx crewforth update): it keeps that chain and runs Crewforth's hooks before it (.claude/git-shim)") s="Crewforth'u güncelleyin (npx crewforth update): o zinciri korur ve Crewforth'un hook'larını önünde çalıştırır (.claude/git-shim)" ;;
+      "trace-blocklist.txt: the placeholder %s is active as it shipped — §4.2 looks for those characters and for no template name; write the template's name in its place, or put the # back") s="trace-blocklist.txt: %s yer tutucusu gönderildiği hâliyle etkin — §4.2 o karakterleri arıyor, bir şablon adını değil; yerine şablonun adını yazın ya da başına # koyun" ;;
+      "§4.2 names no vendor template: .claude/hooks/trace-blocklist.txt holds only its placeholder, so that rule looks for nothing — if this project came from a template, write its name there") s="§4.2 hiçbir üçüncü taraf şablon adı içermiyor: .claude/hooks/trace-blocklist.txt'te yalnız yer tutucu var, yani o kural hiçbir şey aramıyor — proje bir şablondan geldiyse adını oraya yazın" ;;
+      '§4.2 names %s vendor template pattern(s) in trace-blocklist.txt') s="§4.2, trace-blocklist.txt'te %s üçüncü taraf şablon deseni içeriyor" ;;
       'not a git repo — commit gates need: git init && git config core.hooksPath .claude/hooks') s='git deposu değil — commit kapıları için: git init && git config core.hooksPath .claude/hooks' ;;
       "Crewforth's JSON reader is missing (%s) — settings.json cannot be checked") s="Crewforth'un JSON okuyucusu yok (%s) — settings.json denetlenemiyor" ;;
       'update Crewforth') s="Crewforth'u güncelleyin" ;;
@@ -261,13 +269,59 @@ if [ -x .claude/hooks/guard-bash.sh ]; then
   esac
 fi
 
-# 3) core.hooksPath — without it the §4.1/§4.2 commit trace + secret/bloat scan never runs
+# 2c) §4.2's list. trace-blocklist.txt ships the vendor section with a placeholder, `# <vendor-template-name>`,
+#     commented out: until a name stands there §4.2 looks for nothing, and nothing said so (a field note: it stays
+#     unfilled). Two states are told apart. The placeholder made ACTIVE as it shipped (the # removed, the text left)
+#     is a mistake: the rule then looks for those characters. No active line at all is the ordinary state of a
+#     project that came from no template, so it is said once, as information, and is not counted.
+_tb=.claude/hooks/trace-blocklist.txt
+if [ -f "$_tb" ]; then
+  _tbn=0; _tbp=""; _tbon=0
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    _l="${_l%$'\r'}"
+    case "$_l" in
+      '# --- '*4.2*) _tbon=1; continue ;;
+      '# --- '*)     _tbon=0; continue ;;
+    esac
+    [ "$_tbon" = 1 ] || continue
+    case "$_l" in ''|'#'*) continue ;; esac
+    _tbn=$((_tbn+1))
+    case "$_l" in '<'*'>') _tbp="$_l" ;; esac
+  done < "$_tb"
+  if [ -n "$_tbp" ]; then
+    warn "trace-blocklist.txt: the placeholder %s is active as it shipped — §4.2 looks for those characters and for no template name; write the template's name in its place, or put the # back" "$_tbp"
+  elif [ "$_tbn" = 0 ]; then
+    skip "§4.2 names no vendor template: .claude/hooks/trace-blocklist.txt holds only its placeholder, so that rule looks for nothing — if this project came from a template, write its name there"
+  else
+    ok "§4.2 names %s vendor template pattern(s) in trace-blocklist.txt" "$_tbn"
+  fi
+fi
+
+# 3) core.hooksPath — without it the §4.1/§4.2 commit trace + secret/bloat scan never runs on a commit.
+#    .claude/git-shim is Crewforth's too: it is where the updater points git when the project has a hook chain of
+#    its own (husky, .git/hooks), and each shim there 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 one command that disconnects the project's own hooks. The advice for a project with a chain
+#    of its own is the updater, which keeps the chain.
 if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   HP="$(git config --get core.hooksPath 2>/dev/null || true)"
+  # A hook chain of the project's own that an unset or foreign core.hooksPath would be running today.
+  _own=0; { [ -d .husky ] || [ -x .git/hooks/pre-commit ] || [ -x .git/hooks/commit-msg ]; } && _own=1
   case "$HP" in
     */.claude/hooks|.claude/hooks) ok "core.hooksPath -> %s (commit-time gates active)" "$HP" ;;
-    "") bad "core.hooksPath is unset — commit trace/secret/bloat gates are INACTIVE" "git config core.hooksPath .claude/hooks" ;;
-    *)  bad "core.hooksPath -> %s (not Crewforth's hooks)" "git config core.hooksPath .claude/hooks" "$HP" ;;
+    */.claude/git-shim|.claude/git-shim)
+      _shb=""
+      for h in pre-commit commit-msg; do
+        { [ -x "$HP/$h" ] && grep -q '\.claude/hooks/' "$HP/$h" 2>/dev/null; } || _shb="$_shb $h"
+      done
+      if [ -z "$_shb" ]; then ok "core.hooksPath -> %s (Crewforth's hooks run first, then the project's own — commit-time gates active)" "$HP"
+      else bad "core.hooksPath -> %s, but the shim there does not run Crewforth's hook:%s" "update Crewforth (npx crewforth update), which writes the shim again" "$HP" "$_shb"; fi ;;
+    "") if [ "$_own" = 1 ]; then
+          bad "core.hooksPath is unset — commit trace/secret/bloat gates are INACTIVE" "update Crewforth (npx crewforth update): this project has hooks of its own, and the update runs Crewforth's before them instead of replacing them"
+        else
+          bad "core.hooksPath is unset — commit trace/secret/bloat gates are INACTIVE" "git config core.hooksPath .claude/hooks"
+        fi ;;
+    *)  bad "core.hooksPath -> %s (not Crewforth's hooks)" "update Crewforth (npx crewforth update): it keeps that chain and runs Crewforth's hooks before it (.claude/git-shim)" "$HP" ;;
   esac
 else
   warn "not a git repo — commit gates need: git init && git config core.hooksPath .claude/hooks"