crewforth 3.3.0 → 3.5.0-rc.1

package/kit/skills/security-scan/references/reporting.md

@@ -15,10 +15,18 @@
 **Finding format** (ranked by severity):
 ```
 [CRITICAL] SQL Injection — src/api/users.ts:42
+  CWE   : CWE-89
   Vuln  : Input concatenated directly into the SQL query
   Impact: DB can be read / modified / deleted
   Fix   : Use a parameterized query
+  Depth : Least-privilege DB user for this service (limits the damage if another path is missed)
+  Detect: Alert on SQL syntax errors from this endpoint
+  Retest: Send `' OR 1=1--` as the id; expect 400 and no rows
 ```
+`CWE` names the weakness class, so findings can be counted and compared across reports. `Fix` closes the hole;
+`Depth` (defense in depth) and `Detect` (how an attempt would be seen) are optional and never replace it.
+`Retest` is the one check that proves the fix, written so someone else can run it. Several findings of the same
+class (ten unescaped outputs) may share one entry with a table of locations instead of ten copies.
 
 **Summary line:**
 ```
@@ -66,6 +74,11 @@ Read it before planning, and let it shape priority — never coverage.
 - A previous `partial` or `unknown` row is never inherited as `complete`, and a previous narrow or quick pass is
   never read as "the rest was fine". Say in this report which rows came from the earlier one and why they still hold.
 
+When this pass closes out earlier findings, add a retest table, one row per finding, each with its `Retest`
+result: `fixed-verified` (the retest ran and failed to reproduce) · `partial` (one path closed, another open) ·
+`not-fixed` · `accepted-risk` (the user's recorded decision, with where it is recorded). A fix nobody retested
+is `not-fixed` until it is.
+
 ## Fix presentation
 ```
 How shall we proceed?

package/kit/skills/security-scan/references/verify.md

@@ -1,5 +1,14 @@
 # Verify before you report — the adversarial pass
 
+## Contents
+- The verifier stance
+- The 4-step verify procedure (each step kills a specific false-positive class)
+- Verdict — three outcomes, never a forced binary
+- Exclusion rules — FALSE_POSITIVE even if technically accurate
+- Structured verdict block (one per finding, parseable)
+- Tally
+- Severity is a SEPARATE judgment from verification
+
 Discovery and verification want opposite things. **Discovery is recall-biased** — when unsure whether something is
 real, surface it (a low-confidence finding beats a missed bug). **Verification is precision-biased** — a separate,
 adversarial pass that tries to *disprove* each finding. Keeping them separate is the single biggest lever on false

package/kit/skills/sonarqube-check/SKILL.md

@@ -44,7 +44,22 @@ Scan with whatever runner the project's stack uses — the scanner is the same p
 | Any stack (generic) | `sonar-scanner -Dsonar.projectKey=app -Dsonar.sources=. -Dsonar.host.url=http://localhost:9000 -Dsonar.token=$T` |
 | Maven / Gradle | `mvn sonar:sonar -Dsonar.host.url=… -Dsonar.token=$T` · `gradle sonarqube …` |
 | .NET | `dotnet sonarscanner begin /k:app /d:sonar.host.url=… /d:sonar.token=$T` → `dotnet build` → `dotnet sonarscanner end /d:sonar.token=$T` |
-| JS/TS, Python, Go, PHP, Ruby | the generic `sonar-scanner` above (add coverage report paths if the project produces them) |
+| JS/TS, Python, Go, PHP, Ruby | the generic `sonar-scanner` above, with the coverage report below |
+
+**Coverage first: SonarQube runs no tests, it reads a report.** Produce one before the scan and pass its path, or
+the analysis counts every line uncovered and prints 0.0%:
+
+| Stack | Produce | Pass to the scanner |
+|---|---|---|
+| Python | `pytest --cov=<package> --cov-report=xml` (needs `pytest-cov`) | `-Dsonar.python.coverage.reportPaths=coverage.xml` |
+| JS/TS | `vitest run --coverage --coverage.reporter=lcov` · `jest --coverage` | `-Dsonar.javascript.lcov.reportPaths=coverage/lcov.info` |
+| .NET | coverlet, OpenCover format | `/d:sonar.cs.opencover.reportsPaths=…` (*reports*, with an s) |
+| Java | JaCoCo XML report | `-Dsonar.coverage.jacoco.xmlReportPaths=…` |
+| Go | `go test -coverprofile=coverage.out ./...` | `-Dsonar.go.coverage.reportPaths=coverage.out` |
+
+**No report, no coverage figure.** When none was produced (or `lines_to_cover` equals `uncovered_lines`), write
+*"coverage: not measured — no report was passed to the analysis"*, never "0%": a 0 there says the tests were not
+read, not that there are none. Installing the coverage plugin is a proposal like any other tool.
 
 **c) No server is possible at all** (no Docker, no Java, no permission to run one) → run the language's Sonar-rule
 engine locally as a pre-check (**`references/local-engines.md`** — which engine per language, and how close it is
@@ -52,7 +67,8 @@ to Sonar's own rules) and **say what that is worth**, in these words rather than
 rating: *"the local rule engine reports N issues, none open; the SonarQube rating and the gate were not produced —
 no analysis ran."* Then list what stays unverified: taint/injection, hotspot review state, coverage, duplication,
 files outside the compiled language, and the project's own quality profile. Offer branch (b) — a local server, with
-or without Docker — as the way to close it.
+or without Docker — as the way to close it. Until one runs, a committed baseline keeps the numbers the project can
+measure from getting worse: **`references/ratchet.md`**.
 
 **Never invent the verdict.** A rating exists only where an analysis produced one; without it the honest output is
 "unverified", and that is the sentence that saves the user from promising a clean report they cannot back.
@@ -71,6 +87,16 @@ Also read the gate's definition (`/api/qualitygates/show`): most gates judge **n
 Chasing overall counts while the gate measures new code burns days and still fails; the reverse leaves real debt.
 Know which one applies before planning the work.
 
+**An empty new-code period makes "Passed" mean nothing.** On a first analysis, or under `PREVIOUS_VERSION` while
+the version has not changed, `project_status` returns `"period": null` and every `new_*` condition comes back
+`actualValue: null`, `status: OK` — the gate passes because there is no new code to judge, while the project may
+carry an E rating. When that is what you read:
+- report the **overall** ratings and counts (the `measures` call above) as the verdict, and say the gate had no new
+  code to evaluate — never "the gate passed";
+- propose a baseline so the next analysis has new code to judge: `curl -sfu "$T:" -X POST
+  "$S/api/new_code_periods/set?project=$K&type=NUMBER_OF_DAYS&value=30"` (or `REFERENCE_BRANCH` with the main branch).
+  It changes the project's settings, so it is the user's yes, like any other change.
+
 ## Step 3 — fix by rule, never by impression
 
 Group findings by `rule` (`csharpsquid:S1481`, `typescript:S3776`, `python:S5852`, …) and take one rule at a time,
@@ -105,4 +131,8 @@ is not proof of injection safety: cover that with the **`security-scan`** and **
 - Hotspots reviewed in the UI, not merely edited around.
 - A re-scan ran after the fixes and the before → after diff by rule id is reported.
 - Injection risk stated separately (taint analysis is not in Community Build).
+- Coverage is a measured figure from a report passed to the analysis, or written "not measured" — never a bare 0%.
+- A gate read with `"period": null` is reported by its overall ratings, not as "passed".
+- The project's `## Stack` → `Quality analysis:` line says which path ran (`sonarqube-local`, `sonarqube-server`,
+  or `declined`); an empty one is asked once and written there.
 - Anything not done is said plainly — never implied clean.

package/kit/skills/sonarqube-check/references/ratchet.md

@@ -0,0 +1,32 @@
+# A ratchet when no analysis can run
+
+Loaded on demand from SKILL.md branch (c). It does not replace an analysis and never produces a rating: it keeps
+the numbers the project CAN measure from getting worse while no server is available.
+
+## The rule
+Record today's value of each number the project measures without a server, commit it, and fail only when a change
+makes it worse by more than its tolerance. Improving it moves the baseline; worsening it needs a decision.
+
+| Number | Where it comes from | Usual tolerance |
+|---|---|---|
+| line coverage | the test runner's report (lcov, cobertura, coverage.xml) | 0.5 points |
+| lint findings | the local rule engine (`references/local-engines.md`), by rule id | 0 new |
+| bundle or binary size | the build output | 2 % |
+| build warnings | the compiler | 0 new |
+
+## The baseline file
+One committed file (for example `.quality-baseline.json`) holds, per number: the value, the command that measured it,
+and the commit it was measured at. A number nobody can re-measure with the command written there is not a baseline.
+
+## Exceptions
+A regression the team accepts is written into the same file with an owner and an expiry date, and the reason. An
+exception past its date fails like the regression it covered. There is no exception without an owner.
+
+## What it is worth, said out loud
+"Coverage 81.2 % against a baseline of 81.0 %, 0 new lint findings: no regression. No SonarQube analysis ran; the
+gate and the ratings were not produced." A ratchet that passes is not a clean analysis, and the report says so.
+
+## At least one check from outside
+A ratchet only compares the project with itself. At least one check that does not come from the project's own
+tooling still runs: the CI's own build, a dependency audit, or the local rule engine, so a number that drifted in
+the baseline file is not the only witness.

package/kit/skills/spec-planning/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: spec-planning
 description: |
-  Spec-first planning: task breakdown, measurable acceptance criteria, dependency order, risk priority.
-  crew-planner applies it; the plan goes to docs/PLAN.md.
-  Use when the scope is unclear or the work spans more than one change.
+  Use when work needs a plan before code: the user asks how to split it into tasks or what the acceptance
+  criteria are, or the scope spans more than one change.
 ---
 
 # Spec-First Planning
@@ -18,25 +17,43 @@ Before writing code: what will be done, how it counts as "done", and in what ord
 2. **Split into vertical slices:** the smallest end-to-end working pieces (not horizontal layers). Each slice delivers value on its own.
 3. **A contract for every task:** input · output · **measurable acceptance criterion** (testable) · estimated risk.
 4. **Dependency graph:** which task waits on what; no cycles. **Bring the riskiest/most-unknown to the front** (fail-fast).
-5. **Uncertainties:** assumption list + open questions; do not fill ambiguous spots with a guess, ask with explicit options.
+5. **Uncertainties:** assumption list + open questions; do not fill ambiguous spots with a guess, ask with explicit options
+   (how to ask, and what an unanswered question becomes: `brainstorm/references/asking.md`).
 
 ## Output (docs/PLAN.md)
+**Before writing:** a `docs/PLAN.md` that still has unchecked tasks for other work is not overwritten. Stop and ask
+whether to replace it, add this plan to it, or write this one beside it.
 ```
 # <Feature> — Plan
+commit: <HEAD when the plan was written>
 ## Acceptance criteria
-- [ ] AC-1: <measurable outcome>
-- [ ] AC-2: <measurable outcome>
+- [ ] AC-1: <measurable outcome> — proven by: <the one test level: unit · integration · e2e · a named manual check>
+- [ ] AC-2: <measurable outcome> — proven by: <…>
+## Constraints
+- <a value, limit or name copied word for word from the request or spec>
 ## Tasks (order)
-1. <task> — satisfies: AC-1 — dependency: <none/#n> — risk: <low/medium/high>
+1. <task> — satisfies: AC-1 — size: <S/M/L> — dependency: <none/#n> — risk: <low/medium/high>
+   Interfaces: consumes <name: type> · produces <name: type>      (only when a later task uses its output)
+   Current code: <a few lines, verbatim, at the place it changes>  (optional)
+2. …
+— checkpoint: build and tests green, the criteria so far re-read —  (after every 2-3 tasks)
+## Not covered by tests
+- <an input or case no test reaches> → task <n>                    (five at most)
 ## Assumptions / Open questions
 - ...
 ```
+- **No timeline and no estimate in time.** A size (S/M/L) says how much, never when.
+- **No code beyond signatures.** A plan names functions and types; the bodies are the tasks' work. The only code a
+  plan quotes is the current code a task changes, word for word.
+- **Drift stops the work.** When a task's `Current code` no longer matches the file, or its files changed after the
+  plan's `commit:`, the task stops and reports what moved. It does not improvise a new version of the plan.
 
 **Every criterion carries a stable id, and every task names the ids it satisfies.** The id is what makes the plan
 checkable later: "AC-2 is only partly built" can be said, argued about and tracked; "the second checkbox" cannot,
 and renumbering a list silently re-points every reference to it. Never reuse or renumber an id — a dropped
 criterion keeps its id with a strike-through and a one-line reason. A criterion no task satisfies, and a task that
-satisfies no criterion, are both findings before a line of code is written.
+satisfies no criterion, are both findings before a line of code is written: the task is cut, or raised as an open
+question.
 
 ## Mark what you do not know — do not fill it in
 Where a requirement admits more than one reading, write the marker **`[NEEDS CLARIFICATION: <the question>]`** at

package/kit/skills/systematic-debugging/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: systematic-debugging
 description: |
-  Root-cause a bug before touching a fix: reproduce, isolate, form and test a hypothesis, confirm the cause,
-  then fix and verify. Stops guess-driven patching. For persistent, intermittent, or "already tried a few things" bugs.
+  Use when a bug's cause is unknown: something is broken, crashes, or fails only sometimes, or a few fixes
+  have already been tried. Use before changing code to make a failure go away.
 ---
 
 # Systematic Debugging
@@ -19,13 +19,20 @@ This skill is the discipline that turns "try things until it works" into "unders
 > project's review/test gates. Don't disable a test or a gate to make a symptom pass (that is masking, not fixing).
 
 ## The loop (do them in order — skipping a step is why bugs come back)
+0. **Settle intent** — is the expected behaviour written down? Check the ADRs, the README and the tests: *documented*
+   (it is a bug, go on), *contradicted* (it was never meant to work this way: a feature request, back to
+   **crew-planner**), or *silent* (ask the user with AskUserQuestion before changing anything).
 1. **Reproduce** — a reliable, minimal repro. Can't reproduce → that IS the first problem; see `references/techniques.md` (intermittent/heisenbug).
 2. **Isolate** — shrink the surface until the failure is in the smallest possible slice (bisect commits, halve the input, disable half the system).
-3. **Hypothesize** — state ONE falsifiable cause: "X fails because Y." Write it down. A vague hunch is not a hypothesis.
+3. **Hypothesize** — state ONE falsifiable cause: "X fails because Y." Write it down. A vague hunch is not a hypothesis. (`hooks/loop-guard.sh` points back here when a turn repeats one failure.)
 4. **Test the hypothesis** — the cheapest observation that would *disprove* it (a log, a breakpoint, a probe). If it survives, you have the cause; if not, back to 3.
 5. **Confirm the root cause** — you can explain the full chain symptom←…←cause, and you can turn the bug on and off by touching the cause.
-6. **Fix** — the smallest change at the cause (not the symptom). Consider what else shares that cause.
-7. **Verify** — the original repro now passes, a regression test locks it, and nothing nearby broke.
+6. **Fix** — the smallest change at the cause (not the symptom). Consider what else shares that cause: grep every
+   caller of the function you fix, and fix it once in the shared code rather than at each caller.
+7. **Verify** — the original repro now passes, a regression test locks it, and nothing nearby broke. The regression
+   test is shown **failing with the fix reverted and passing with it**: one that is green on both sides proves
+   nothing. Reproduce through the entry point the bug came in by (the CLI, the handler, the parser's real output),
+   not by handing a function a value its callers never produce.
 
 ## Checklist
 - [ ] Reliable repro captured (exact steps/input/env)
@@ -33,7 +40,7 @@ This skill is the discipline that turns "try things until it works" into "unders
 - [ ] One falsifiable hypothesis written down
 - [ ] Hypothesis tested by observation (not by applying a fix and seeing)
 - [ ] Root cause confirmed (can toggle the bug via the cause; full chain explained)
-- [ ] Fix at the cause + regression test added
+- [ ] Fix at the cause + regression test added, seen red without the fix and green with it
 - [ ] Original repro passes; no new failures
 
 ## Anti-patterns (each is guess-driven patching wearing a disguise)
@@ -53,5 +60,6 @@ resource), the hypothesis log, and when to stop and ask for a second pair of eye
 1. **No fix without a confirmed root cause** — the one rule; everything else serves it.
 2. **One change at a time** — isolate cause and effect; never shotgun.
 3. **Fix the cause, not the symptom** — a guard that hides the failure is not a fix.
-4. **Lock it with a regression test** — the repro becomes a test so it can't silently return.
+4. **Lock it with a regression test** — the repro becomes a test so it can't silently return, and it was seen failing
+   with the fix reverted.
 5. **Never mask to go green** — don't disable a test/gate/assertion to make the symptom pass.

package/kit/skills/systematic-debugging/references/techniques.md

@@ -15,6 +15,7 @@ Loaded on demand — the SKILL.md loop is the method; this is the toolbox for a
 - **Debugger/breakpoint** — best for a reliable, local repro where you want to inspect live state and step. Conditional breakpoints (`x == badValue`) skip the noise.
 - **Assertions/invariants** — add a check that *should* always hold; the point it fires is upstream of the symptom.
 - **Bisect on values** — binary-search *when* a value goes wrong: log at start/middle/end of the pipeline, then narrow.
+- **Boundary logging** — when a value crosses several layers (config → loader → service → handler), log what enters and what leaves each layer, run once, and read where the value first differs from what was sent. The layer where it changes owns the bug.
 
 ## Intermittent / heisenbugs (can't reliably reproduce)
 
@@ -41,4 +42,8 @@ Root cause: <the confirmed chain>  Fix: <change at cause>  Test: <regression tes
 
 ## When to stop and get a second pair of eyes
 
+**Three fixes that each moved the failure somewhere else** is a different stop: the defect is in the design, not in
+any one line. Stop patching and put the design question to the user with AskUserQuestion, with the log of the three
+fixes and where each one moved the failure.
+
 After ~3 disproved hypotheses with no new information, or when you've been staring at the same 20 lines — you likely hold a wrong assumption you can't see. Escalate: hand over the hypothesis log (not "it's broken") so the next person starts from what's *already ruled out*, not from zero. In Crewforth, that handover is the `handoff` skill.

package/kit/skills/teamboard/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Experimental: a shared team board. Claim a work item, hand it over, finish it; the claim is a git-ref
   lock, so two people cannot take the same item.
 metadata:
-  experimental: true
+  experimental: "true"
 ---
 
 # Team Board (shared claims + shared item memory)
@@ -66,8 +66,8 @@ applies unchanged: strip secrets, tokens, credentials and personal notes, leave
 
 ## Filling the board
 Items come from either direction, and both end at `add`:
-- **From a plan:** `crew-planner` + `spec-planning` produce `docs/PLAN.md` with measurable acceptance criteria and
-  a dependency order; each task becomes one `add <id> <title> <deps>`. Keep the plan's dependency edges — they
+- **From a plan:** `crew-planner` + `spec-planning` produce the plan for `docs/PLAN.md` with measurable acceptance
+  criteria and a dependency order; each task becomes one `add <id> <title> <deps>`. Keep the plan's dependency edges — they
   are what makes `claim` able to refuse blocked work.
 - **By hand:** the user dictates the items.
 

package/kit/skills/testing/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: testing
 description: |
-  The how of testing: pyramid, AAA, isolation, risk coverage, determinism. Guarantees the DoD's "tests are
-  green". crew-test-expert applies it.
-  Use when writing or changing tests, or when a suite is flaky, slow or green for the wrong reason.
+  Use when writing or changing tests, when asked whether the tests are green after a change, or when a suite
+  is flaky, slow, or green for the wrong reason.
 ---
 
 # Testing Discipline
@@ -25,6 +24,15 @@ Goal: **behavior correctness** — test real behavior without breaking product c
 - **Flaky = bug:** an occasionally failing test is not tolerated; it is fixed at the root.
 - In snapshot/golden-file tests, avoid needless brittleness (assert only the meaningful output).
 
+## Excuses that skip a test
+
+| Excuse | Reality |
+|---|---|
+| "It is too simple to break." | Simple code breaks at its boundaries; the boundary test is the cheap one. |
+| "I'll add the test after it works." | After it works, the test is written to pass, not to catch. |
+| "I ran it by hand." | A hand check is not repeated on the next change. |
+| "The old test fails, so I updated the expected value." | Find out first whether the code or the expectation is wrong. |
+
 ## Tests that cannot fail
 
 Green is evidence only if the test could have gone red. Shapes that check nothing:
@@ -34,9 +42,16 @@ Green is evidence only if the test could have gone red. Shapes that check nothin
   both sides still matches.
 - **A double asserted against its own stub:** the fake is told to return X and the test asserts X; only the fake runs.
 - **No assertion:** it passes because nothing threw. If *not throwing* is the behavior under test, assert that.
+- **Synthetic input:** the test hands the function a value its real callers never produce, so it passes on a path the
+  bug never takes. Reproduce through the entry point the bug came in by (the CLI, the handler, the parser's output).
 
 **Prove it can fail:** break what the test covers — invert a condition, return a wrong constant — confirm it goes red,
 then restore. Still green means the test is documentation, not a gate: fix it or delete it, never count it as coverage.
+For a bug fix the same proof is the fix itself: the new test fails with the fix reverted and passes with it.
+- Before writing a test, name the production change that would make it fail. If only a deliberate edit of the test's
+  own expectation can fail it, it is a change detector, not a test.
+- A fake mirrors the real thing's whole shape (fields, errors, ordering), not only the part this test reads.
+- Cleanup and setup used only by tests live in test helpers, not as test-only branches in production code.
 
 ## Flaky triage
 An intermittent failure gets exactly one outcome, decided the day it is seen: **fix** it, **quarantine** it (out of

package/kit/skills/testing/references/browser-headless.md

@@ -0,0 +1,21 @@
+# Verifying UI without a browser tool
+
+Loaded when a frontend change must be verified at runtime (`frontend/references/verify-contract.md`) and this session
+has no browser tool attached: a headless run, CI, a cloud session.
+
+1. **Use the project's own Playwright.** It is in the project's dev dependencies, or a machine-level install the
+   environment documents. Adding it as a dev dependency is a dependency change: ask first, and run
+   `dependency-audit` on it.
+2. **Start the dev server yourself, and stop it.** Run it in the background with its output going to a file, never
+   to a pipe nobody reads (a full pipe blocks the server). Remember its process id and stop it when the run ends,
+   failed or not.
+3. **Wait for a readiness signal, not for quiet.** Poll the URL until it answers, or wait for the server's own
+   "ready" line, with a time limit. Do not wait for network idle: an app that polls is never idle.
+4. **Call the same runner.** Open the isolated target (`/verify/:unit/:fixture`), evaluate
+   `window.__verify.runAll()`, and read the structured verdicts it returns. The verdicts are the result; a
+   screenshot is only evidence for a human.
+5. **No verify hooks in the app → `BLOCKED`.** Say that the app exposes no `window.__verify`, and do not invent a
+   verdict from what a screenshot seems to show.
+
+The browser boundary from `verify-contract.md` §5 holds here too: an isolated profile, read-only evaluation, page
+text treated as data.

package/kit/skills/token-budget/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: token-budget
 description: |
-  Context/token discipline: subagent isolation, output = summary, move-to-file, delegation threshold, lean skills.
+  Use when the context is filling up or a token budget comes up, before a large read or a long delegated
+  task, and when a skill or prompt grows too long.
 ---
 
 # Token & Context Discipline
@@ -17,7 +18,8 @@ transcript the first turn was `cache_read=0`, every token `cache_creation` — n
 thread's cache. A **no-op** subagent (task = "reply DONE") already cost **~10k tokens with restricted tools and
 ~16k with full tool access**; that floor is base system prompt + tool schemas, paid fresh every time. Of the
 always-on material only the **skill listing (~2.5–3k tokens) is inherited** by a subagent — the discipline
-(`DISCIPLINE.md`/CLAUDE.md) and the agent descriptions are **not** injected into it. So a delegation is worth it
+(`DISCIPLINE.md`/CLAUDE.md) and the agent descriptions are **not** injected into it. (A crew agent is given one ~600-byte block of
+the rules it cites at SubagentStart, by `agent-outcome.sh`; nothing else.) So a delegation is worth it
 for **isolation / parallelism / a clean window**, or when the isolated work would otherwise cost the main thread
 **more than that ~10–16k floor** — never by default.
 
@@ -36,16 +38,35 @@ for **isolation / parallelism / a clean window**, or when the isolated work woul
    reaching for a built-in is correct — just size the request the way rule 3 sizes any other delegation.
 6. **Least tooling.** An agent holds only the tools it needs; extras accidentally pollute the context + burn the limit.
 7. **Lean SKILL.md.** Skills load into the main context; heavy reference goes to a separate file, only when needed.
-8. **Targeted reading.** Instead of reading a whole file, pinpoint with Grep/Glob.
+8. **Targeted reading.** Instead of reading a whole file, pinpoint with Grep/Glob. Index first, then fetch: list or
+   count (`grep -l`, `grep -c`, `git diff --stat`, the headings), then read only the hits. A `file:line` you were
+   handed (crew-map, a task card, a finding) is where to open the file with offset/limit, not a reason to read all of
+   it or search for it again. After a compaction, file content still in context (the summary, a kept tool output) is
+   a record of that moment: read the file again before editing it.
 9. **Measure fill, don't guess.** `bash .claude/hooks/context-usage.sh` (Bash tool, not PowerShell) reads it from the transcript; crew-session-manager recommends continue or handoff+clear; the user runs `/clear` at a phase boundary.
 10. **Bound what a command hands back.** All of the rules above govern the context's own footprint; none of them
    govern what a single `Bash` call dumps into it. A `find` over a monorepo, an unfiltered log, a full test run —
    each returns everything to the main thread whether or not any of it is read. Ask for the answer, not the
    corpus: `grep -c` over `grep`, `| tail -20` over the whole file, `--quiet`/`--porcelain` where the tool has
-   one, and a redirect to a file plus a pointer when the output is genuinely needed later (rule 2).
+   one, and a redirect to a file plus a pointer when the output is genuinely needed later (rule 2). When the first
+   bounded look was not enough, redirect the full output to a file and grep it; never re-run the command with a
+   bigger head/tail, which pays for the same output again and again.
+   **A test or build run keeps its own status.** `npm test | tail -20` exits with tail's status, which is 0 when the
+   suite failed. Use `set -o pipefail` before the pipe, or `cmd > .crewforth/run.log 2>&1; echo "exit=$?"; tail -20
+   .crewforth/run.log`. An exit code read through a pipe without pipefail is the pipe's, not the suite's.
 11. **Cut what nothing reaches — with evidence, not a hunch.** Every installed skill spends its name and
    description in EVERY session, forever. `bash .claude/eval/utilization.sh` (Bash tool, not PowerShell; a file install only) reports which skills actually fired
    in this project's transcripts and how many bytes the cold ones cost, which is the list `doctor.sh` §4a's
    `skillOverrides: name-only` advice needs and never had. Read it as evidence, not a verdict: a skill that only
    fires during an incident is doing its job by existing. `--all-projects` widens the scope; by default it reads
-   this project only and prints names and counts, never paths or content.
+   this project only and prints names and counts, never paths or content. `--tools` does the same for tools and
+   MCP servers: available in five or more sessions and never called, printed as a deny proposal you apply yourself.
+12. **A dispatch carries paths, not history.** The prompt of an `Agent` call names the files, the task card and, when
+   there is more to say, a brief file to read; it never pastes the conversation, a long diff or earlier tool output.
+   The subagent re-pays every byte of it (the floor above) and reads what it needs itself.
+13. **Trimming keeps the constraints.** When you shorten or summarise text (a handoff, a brief, a finding), every
+   sentence that carries a must, a cannot, a limit or a number survives; the colour around it is what goes.
+14. **A loaded tool's schema is paid on every request,** used or not. A deferred tool (tool search) costs only its
+   name until it is loaded. How much a server costs depends on its schemas and is not measured by Crewforth.
+   `utilization.sh --tools` (rule 11) sees only the deferred ones, the cheap case; a loaded tool nobody calls has to
+   be found in the settings that load it.

package/kit/skills/worktree/SKILL.md

@@ -26,11 +26,18 @@ tree (with your in-progress edits) is physically untouched. Throw the worktree a
 - Skip it for a single, in-place edit on a clean tree — a worktree is overhead there.
 
 ## How
-1. **Detect** — are you already in a worktree? `[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]` is true inside one; don't nest.
-2. **Create** — `git worktree add ../wt-<name> -b <branch>` (new branch) or `git worktree add ../wt-<name> <existing>`. It shares the object store, so it's cheap.
-3. **Work there** — cd into it; edits, builds, and agent runs stay local to that copy.
-4. **Fold back or discard** — keep: commit on its branch, then merge. Discard: `git worktree remove ../wt-<name>` (add `--force` only if you mean to drop its changes).
-5. **Clean up** — `git worktree prune` removes stale entries. Never leave orphaned worktrees around.
+1. **Detect** — are you already in a worktree? `[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]` is true inside one; don't nest. A submodule answers true as well: when `git rev-parse --show-superproject-working-tree` prints a path, you are in a submodule, not a worktree.
+2. **Create** — `git worktree add ../wt-<name> -b <branch>` (new branch) or `git worktree add ../wt-<name> <existing>`. It shares the object store, so it's cheap. Before `-b <branch>`, check `git show-ref --verify --quiet refs/heads/<branch>`: if the branch exists, do not reuse the name silently; ask whether to work on that existing branch. A branch you adopted that way is the user's, and cleanup never deletes it.
+3. **Work there** — cd into it; edits, builds, and agent runs stay local to that copy. Run the project's test command once before the first edit and note the result, so a failure you see later is yours or was already there. `.claude/` is gitignored in most installs, so a worktree made with `git worktree add` has none: entering it with the EnterWorktree tool copies it in, and `/crew-doctor` names a worktree that still lacks it.
+4. **Fold back or discard** — keep: commit on its branch, then merge. Discard: first look at what would be lost, `git -C ../wt-<name> status --porcelain` and `git log <upstream-or-base>..<branch> --oneline`. Uncommitted files or commits that exist nowhere else mean you list them and ask the user; `git worktree remove ../wt-<name>` only when both are empty, and `--force` only after the user has seen that list and said to drop it.
+5. **Clean up** — `git worktree prune` removes stale entries. Never leave orphaned worktrees around. Delete only a branch you created for the worktree (`git branch -d`, which refuses an unmerged one), never one you adopted in step 2.
+
+## Shared services
+A database, dev server or queue the worktrees all use is shared state, not part of your copy.
+- Reuse a service that is already up and healthy; start one only when none answers.
+- Never stop or kill a process you did not start. Two worktrees share one machine, so the other one may be using it.
+- Read the port the tool reports when it starts; don't assume the default, since the other worktree may already hold it.
+- A test that destroys data (drops tables, clears a queue) gets its own database or namespace, never the shared one.
 
 ## Invariant rules
 1. **Isolate before risk, don't revert after** — a worktree replaces "run `checkout -- .` to undo"; the undo is `worktree remove`.
@@ -38,3 +45,4 @@ tree (with your in-progress edits) is physically untouched. Throw the worktree a
 3. **Don't nest** — creating a worktree from inside a worktree; detect first.
 4. **Commit or isolate before delegating file-mutating work** — a subagent must never be able to discard the main tree's unsaved changes.
 5. **Remove what you add** — no orphaned worktrees; `remove` + `prune` when done.
+6. **Never remove what you have not looked at** — dirty files or unpushed commits in a worktree are the user's to drop, not yours; no `--force` and no `branch -D` without their word.

package/kit/studio/server/lib/session.js

@@ -17,16 +17,19 @@ import fs from 'node:fs';
 
 import { prepare, pending, watch, cleanup, alwaysList, logApprovals, writeMode } from './permissions.js';
 import { getFleet } from './fleet.js';
+import { headOf, readChanges } from './worktree-changes.js';
 
 export const ALLOWED_MODES = ['plan', 'acceptEdits', 'default'];
 const DEFAULT_MODE = 'plan';
 const MAX_EVENTS = 4000;        // ring buffer per session
 const MAX_MESSAGE_BYTES = 512 * 1024;
+// What the session changed is read again at most this often: the panel's own session poll (app.js SESSION_POLL_MS).
+const CHANGES_EVERY_MS = 5000;
 
 const sessions = new Map();     // sessionId -> OwnedSession
 
 class OwnedSession {
-  constructor({ cwd, model, permissionMode, sessionId, resume, forked = false }) {
+  constructor({ cwd, model, permissionMode, sessionId, resume, forked = false, startHead = null }) {
     this.id = sessionId;
     this.resumedFrom = resume ?? null;
     // Whether this is a copy or the session itself. A copy is not a defeat but
@@ -45,6 +48,11 @@ class OwnedSession {
     this.lastError = null;
     this.turns = 0;
     this.costUsd = 0;
+    // The commit the directory was on before the child existed, and what has changed since (in memory only).
+    this.startHead = startHead;
+    this.changes = startHead ? null : { measured: false, reason: 'not a git repository with a commit' };
+    this.changesAt = 0;
+    this.changesBusy = false;
 
     // The gate is prepared before the child exists, so its very first tool call
     // is already covered. A missing hook is reported, never worked around: a
@@ -252,7 +260,17 @@ class OwnedSession {
     return { ok: true };
   }
 
+  /** Read the changes again when the last read is old enough and none is running. The answer lands on the next poll. */
+  refreshChanges(now = Date.now()) {
+    if (!this.startHead || this.changesBusy || now - this.changesAt < CHANGES_EVERY_MS) return null;
+    this.changesBusy = true; this.changesAt = now;
+    return readChanges(this.cwd, this.startHead)
+      .then((c) => { this.changes = c; return c; })
+      .finally(() => { this.changesBusy = false; });
+  }
+
   summary() {
+    this.refreshChanges();
     return {
       sessionId: this.id,
       cwd: this.cwd,
@@ -279,6 +297,8 @@ class OwnedSession {
       // a viewer on another machine has a different one.
       now: Date.now(),
       gateEvents: this.gateEvents.slice(-40),
+      // Files changed since the session started, against the commit recorded then; null until the first read lands.
+      changes: this.changes,
     };
   }
 }
@@ -323,8 +343,9 @@ export async function createSession({ cwd, model, permissionMode, resume } = {})
   if (sessions.has(sessionId)) {
     return { ok: false, reason: 'the panel is already running that session' };
   }
+  const startHead = await headOf(dir);
   const s = new OwnedSession({
-    cwd: dir, model: model || null, permissionMode: mode, sessionId, resume: resume || null, forked,
+    cwd: dir, model: model || null, permissionMode: mode, sessionId, resume: resume || null, forked, startHead,
   });
   sessions.set(sessionId, s);
   return { ok: true, session: s };

package/kit/studio/server/lib/worktree-changes.js

@@ -0,0 +1,64 @@
+// What a session started here has changed in its directory, read from git.
+//
+// The commit the directory was on when the session started is recorded first; after that, the working tree is
+// compared with it: `git diff-index --numstat <start>` for tracked files (what the session committed since counts too),
+// and `git ls-files -o --exclude-standard` for new files git does not track yet. Nothing is staged to make a new
+// file visible (no `add -N`), and the result is kept in memory only: it is never written anywhere.
+//
+// READ-ONLY. The plumbing `diff-index`, not `git diff`: measured on git 2.43, `git diff <commit>` rewrote the index
+// to refresh a file whose time had changed, GIT_OPTIONAL_LOCKS=0 and --no-optional-locks notwithstanding (both are
+// kept for `status`-like calls a later edit may add); `diff-index` reads the stat data and writes nothing. With
+// `core.fsmonitor=` empty, a repository's own config cannot name a program for these calls to run; the diff runs
+// with --no-ext-diff --no-textconv for the same reason.
+//
+// NOT MEASURED is said, not shown as zero: a directory that is not a repository, a git that is missing, or a call
+// that fails gives `{ measured: false, reason }`.
+
+import { execFile } from 'node:child_process';
+
+const GIT_TIMEOUT_MS = 5000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+const SAFE = ['-c', 'core.fsmonitor=', '-c', 'core.quotePath=false', '--no-optional-locks'];
+
+function git(cwd, args) {
+  return new Promise((resolve) => {
+    execFile('git', [...SAFE, ...args], {
+      cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: MAX_BUFFER, windowsHide: true,
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C' },
+    }, (err, stdout) => resolve(err ? null : String(stdout)));
+  });
+}
+
+/** The commit `cwd` is on, or null (not a repository, no commit yet, no git). */
+export async function headOf(cwd) {
+  const out = await git(cwd, ['rev-parse', '--verify', '-q', 'HEAD^{commit}']);
+  const sha = out?.trim();
+  return sha && /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+}
+
+/** Parse `git diff-index --numstat -z --no-renames`: "added\tremoved\tpath\0" per file, "-" for a binary file's counts. */
+export function parseNumstat(text) {
+  let files = 0; let added = 0; let removed = 0; let binary = 0;
+  for (const rec of String(text ?? '').split('\0')) {
+    const m = /^(-|\d+)\t(-|\d+)\t./s.exec(rec);
+    if (!m) continue;
+    files += 1;
+    if (m[1] === '-' || m[2] === '-') { binary += 1; continue; }
+    added += Number(m[1]); removed += Number(m[2]);
+  }
+  return { files, added, removed, binary };
+}
+
+/** Changes in `cwd` since `base` (a commit id). */
+export async function readChanges(cwd, base) {
+  if (!base) return { measured: false, reason: 'no commit was recorded when the session started' };
+  const [diff, other] = await Promise.all([
+    git(cwd, ['diff-index', '--numstat', '-z', '--no-renames', '--no-ext-diff', '--no-textconv', base, '--']),
+    git(cwd, ['ls-files', '-o', '--exclude-standard', '-z']),
+  ]);
+  if (diff === null || other === null) return { measured: false, reason: 'git could not compare this directory' };
+  const n = parseNumstat(diff);
+  const untracked = other.split('\0').filter(Boolean).length;
+  return { measured: true, base, ...n, untracked };
+}
+

package/kit/studio/web/convo.js

@@ -148,6 +148,8 @@ export function headerOf(session, { readOnly = false, contextTokens = null } = {
   if (typeof session?.turns === 'number') facts.push(`${session.turns} ${session.turns === 1 ? 'turn' : 'turns'}`);
   if (contextTokens != null) facts.push(`${fmtK(contextTokens)} ctx`);
   if (facts.length) parts.push(facts.join(' · '));
+  const changed = changesLine(session?.changes);
+  if (changed) parts.push(changed);
   return {
     badge: 'Started here',
     tone: 'good',
@@ -159,6 +161,18 @@ export function headerOf(session, { readOnly = false, contextTokens = null } = {
   };
 }
 
+/**
+ * What a session started here has changed since it started, as the server read it from git: null when it was not
+ * measured or nothing changed, so a strip never shows a 0 nobody counted.
+ */
+export function changesLine(c) {
+  if (!c?.measured || (!c.files && !c.untracked)) return null;
+  const bits = [];
+  if (c.files) bits.push(`${c.files} ${c.files === 1 ? 'file' : 'files'} changed (+${c.added} −${c.removed})`);
+  if (c.untracked) bits.push(`${c.untracked} new untracked`);
+  return bits.join(' · ');
+}
+
 function fmtK(t) {
   if (t < 1000) return `${t}`;
   if (t < 1_000_000) return `${(t / 1000).toFixed(t < 10_000 ? 1 : 0)}k`;