Harden the review loop and the brain arm

.github/workflows/quality.yml

@@ -16,6 +16,30 @@ permissions:
   contents: read
 
 jobs:
+  # The pre-commit and pre-push hooks already scan for secrets, but only on the
+  # machines where `bun run prepare` succeeded, and `--no-verify` is one flag
+  # away. This is the copy that cannot be skipped. It is its own job so it does
+  # not queue behind `bun install`, and it needs the full history: a secret is
+  # in the branch whether it arrived in the last commit or the first.
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # The binary rather than gitleaks-action: the action wants a licence key
+      # for organisation-owned repositories, and pinning the version keeps CI
+      # and the hooks finding the same things.
+      - name: Install gitleaks
+        env:
+          GITLEAKS_VERSION: 8.30.1
+        run: |
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            | sudo tar -xz -C /usr/local/bin gitleaks
+
+      - run: gitleaks git --no-banner --redact .
+
   quality:
     runs-on: ubuntu-latest
     steps:
@@ -27,13 +51,29 @@ jobs:
 
       - run: bun run lint
 
+      - run: bun run knip
+
+      # Known advisories against the installed tree. Every package this can
+      # flag today is a BUILD-time dependency: `codesema` ships with no runtime
+      # dependencies at all, so nothing here reaches a user's machine by being
+      # installed. It still matters, because these packages execute during
+      # `bun run build` and that build produces the `dist` we publish.
+      #
+      # Two transitive packages are pinned past their advisories through the
+      # `overrides` block in the root package.json (postcss, and the nanoid it
+      # pulls). Their parents — vite, vue, @vue/compiler-sfc — still declare
+      # ranges that resolve to the vulnerable versions, so removing the override
+      # silently reintroduces both. Drop an entry only once its parent has moved
+      # on, and confirm with `bun run audit` rather than by reading the range.
+      - run: bun run audit
+
       - run: bun run format:check
 
       - run: bun run typecheck
 
       - run: bun run build
 
-      - run: bun run test
+      - run: bun run test:coverage
 
       - run: bunx publint packages/cli
 

.gitignore

@@ -3,6 +3,10 @@ dist/
 web-dist/
 .codesema/
 *.log
+
+# only produced when the coverage run is asked for a file reporter (lcov);
+# the default text reporter of scripts/coverage-gate.mjs writes nothing to disk
+coverage/
 .DS_Store
 .env
 .env.*

.prettierignore

@@ -4,3 +4,8 @@ web-dist
 coverage
 bun.lock
 CHANGELOG.md
+
+# Committed copies of the brain repo's own generated JSON Schemas
+# (packages/contract/scripts/sync-brain-schemas.mjs). Left in the brain's own
+# export format so a sync is a plain copy, never a copy plus a reformat.
+packages/contract/fixtures/cerveau-schemas

CONTRIBUTING.md

@@ -13,14 +13,19 @@ refuses to start without the embedded web UI that `build` produces.
 
 ## The scripts
 
+Costs measured on 16 cores, caches warm; they are there to tell the cheap
+checks from the expensive ones, not to be hit exactly.
+
 | Script         | What it does                                     | Cost  |
 | -------------- | ------------------------------------------------ | ----- |
-| `lint`         | oxlint over the workspace                        | ~0.2s |
-| `format:check` | prettier, with its cache                         | ~0.8s |
-| `typecheck`    | builds the contract, then tsc ×2 + vue-tsc       | ~5.8s |
+| `lint`         | oxlint over the workspace                        | ~0.3s |
+| `audit`        | known advisories against the installed tree      | ~0.3s |
+| `knip`         | unused files, exports and dependencies           | ~2.7s |
+| `format:check` | prettier, with its cache                         | ~5s   |
+| `typecheck`    | builds the contract, then tsc ×2 + vue-tsc       | ~9.4s |
 | `build`        | contract, then web, then cli                     | ~2.8s |
-| `test`         | builds the contract, then the suite              | ~10s  |
-| `verify`       | typecheck + test, building the contract **once** | ~15s  |
+| `test`         | builds the contract, then the suite in parallel  | ~23s  |
+| `verify`       | typecheck + test, building the contract **once** | ~31s  |
 
 `typecheck:only` and `test:only` skip the contract build, for when you know it
 is already current. `typecheck` and `test` keep it, so both stay usable on
@@ -32,7 +37,7 @@ cached (`node_modules/.cache/prettier/`). Both caches live under
 worktree pays full price, every run after is fast.
 
 The suite runs in parallel **locally only**, on half the cores, computed at run
-time — about 8s instead of 30s. One worker per core sounds better and is not:
+time — 21s instead of 66s. One worker per core sounds better and is not:
 each worker spawns real `git` subprocesses, so the real load runs well past the
 core count, and tests start failing on their timeout rather than on their
 assertions.
@@ -44,18 +49,61 @@ request and then hung for twenty on the merge queue's branch. Locally a person
 is watching and can interrupt; on CI nobody is, and a job that hangs costs far
 more than the twenty seconds it saved.
 
+## Working on the web UI
+
+`packages/cli/web-dist` is a build: editing `packages/web` and re-running
+`bun run build` between every change is the slow way. For hot module
+replacement, run the two halves side by side.
+
+```sh
+bun run dev:web                 # terminal 1: Vite on 5173
+bun run dev:cli workspace       # terminal 2: the CLI, pointed at it
+```
+
+Open the URL the **CLI** prints, not Vite's. This is Vite's backend
+integration mode (https://vite.dev/guide/backend-integration): the CLI keeps
+serving the page, so `/api`, the SSE streams and the tokens it injects into the
+page all stay exactly as they are in a real install, while Vite serves the
+modules and drives HMR. There is no proxy and no second origin to reason about.
+
+`dev:cli` is only a shorthand for `CODESEMA_DEV_VITE=http://localhost:5173`.
+Nothing reads that variable unless you set it, so a published install can never
+fall into this mode; the value must be a loopback origin, since it ends up as a
+`<script src>` on the page. `packages/web/vite.config.ts` pins port 5173 with
+`strictPort`, so a busy port fails loudly instead of drifting to 5174 while the
+CLI keeps pointing at 5173.
+
+The dev shell lives in `devIndexHtml` (`packages/cli/src/serve.ts`) and mirrors
+`packages/web/index.html`; a test fails if the two drift apart.
+
 ## Hooks
 
 Lefthook runs them; `bun run prepare` installs it.
 
-- **pre-commit** — gitleaks on the staged diff, prettier on the staged files
-  (restaged after), oxlint on the staged `.ts`/`.mjs`/`.vue`
-- **pre-push** — `typecheck`, then `test`
+- **pre-commit** (~4s) — gitleaks on the staged diff, prettier on the staged
+  files (restaged after), oxlint on the staged `.ts`/`.mjs`/`.vue`
+- **commit-msg** (~1s): commitlint, cf. `commitlint.config.mjs`
+- **pre-push** (~40s): the contract build, then gitleaks, `typecheck:only`,
+  `knip` and the full suite, all four at once
+
+What sits in which hook follows one rule: a check belongs to the earliest hook
+it can pay for itself in. Anything under a second and scoped to what you staged
+goes in pre-commit; anything that needs the whole workspace, or costs seconds,
+waits for the push; anything that needs the network, the whole history or a
+published artefact stays in CI. That is why `audit`, `format:check` over the
+repo, `publint` and the coverage gate are not in a hook, and why the pre-push
+jobs run as a group: the hook costs what its slowest job costs, so the secret
+scan and `knip` disappear behind the test run.
 
 The pre-push hook is the local gate. There is no need to run the battery by
 hand before pushing; the hook runs it and refuses the push if it fails. Never
 reach for `--no-verify` to get around it.
 
+The one check that also exists server-side is the secret scan: the `secrets` job
+in the `quality` workflow rescans the full history on every pull request, so a
+push that skipped the hooks (or came from a machine where `bun run prepare`
+failed) still gets caught.
+
 ## Branches and merging
 
 `develop` is the integration branch. `main` only ever receives `develop`.