chore: repo policy compliance sweep — test rerun, npx, frozen lockfile, docs (closes #166)

- script/test runs the suite quietly, then reruns it with --verbose on
  failure and always exits 1 (REPO_POLICIES.md conditional verbose rerun
  pattern). New package.json script test:verbose is the -v form of the
  existing jest --forceExit invocation.
- build.js calls node_modules/.bin/tailwindcss instead of npx, which
  would fetch from the registry unpinned if the binary were absent.
- make install uses --frozen-lockfile, so a stale yarn.lock fails the
  target instead of being silently rewritten.
- README Getting Started uses make setup (which also installs the
  pre-commit hook); the Makefile-only targets (install, hooks, build,
  build-debug, clean, dev) are now documented in Entrypoints.
- .dockerignore records why .git is deliberately not excluded.

.dockerignore

@@ -1,3 +1,6 @@
+# .git is deliberately NOT excluded: build.js shells out to `git rev-parse` for
+# build-info stamping and the Dockerfile runs `make build`, so excluding it
+# would make every built extension report commitHash "unknown".
 node_modules
 .DS_Store
 dist

Makefile

@@ -11,7 +11,7 @@ setup:
 	@script/setup
 
 install:
-	@yarn install
+	@yarn install --frozen-lockfile
 
 test:
 	@script/test

README.md

@@ -31,10 +31,13 @@ list exists to detect symbol spoofing attacks and improve UX.
 ```bash
 git clone https://git.eeqj.de/sneak/autistmask.git
 cd autistmask
-make install
+make setup
 make build
 ```
 
+`make setup` is the entrypoint for a fresh clone: it installs dependencies from
+the lockfile and installs the git pre-commit hook.
+
 Load the extension:
 
 - **Chrome**: Navigate to `chrome://extensions/`, enable "Developer mode", click
@@ -97,6 +100,19 @@ provide:
 - `script/precommit` — run by the git pre-commit hook; runs `script/check`
 - `script/install-precommit` — install the git pre-commit hook
 
+The Makefile shims to those. It also carries a few targets that have no
+`script/` counterpart and are Makefile-only conveniences:
+
+- `make install` — `yarn install --frozen-lockfile` on its own, without the rest
+  of `script/bootstrap`. Frozen so a stale `yarn.lock` fails instead of being
+  silently rewritten. Use `make setup` for a fresh clone.
+- `make hooks` — shims to `script/install-precommit`
+- `make build` — build the extension into `dist/chrome/` and `dist/firefox/`
+- `make build-debug` — the same build with `AUTISTMASK_DEBUG=1` (see
+  [Debug Builds](#debug-builds))
+- `make clean` — remove `dist/`
+- `make dev` — build in watch mode
+
 ## End-to-End Tests
 
 `make test-e2e` builds `dist/chrome/` and drives the **real popup in a real

TODO.md

@@ -44,6 +44,10 @@ undefined identifiers, which is how
 
 # Completed Steps
 
+- 2026-08-11: Policy compliance sweep — conditional verbose test rerun, local
+  Tailwind binary instead of `npx`, `--frozen-lockfile` on `make install`, and
+  the Makefile-only targets documented in the README
+  ([#166](https://git.eeqj.de/sneak/AutistMask/issues/166)).
 - 2026-08-11: README Screen Map rebuilt from the code — every screen, element
   and transition re-verified against `src/popup/`
   ([#164](https://git.eeqj.de/sneak/AutistMask/issues/164)).

build.js

@@ -115,8 +115,17 @@ async function build() {
     // build that never gets around to writing one cannot be verified against
     // a stale list.
     fs.rmSync(BUNDLE_MANIFEST, { force: true });
+    // The locally installed binary, not `npx` — npx silently fetches from the
+    // registry when the binary is absent, which is an unpinned network fetch
+    // in the middle of a build.
+    const tailwindBin = path.join(
+        __dirname,
+        "node_modules",
+        ".bin",
+        "tailwindcss",
+    );
     execSync(
-        `npx @tailwindcss/cli -i ${tailwindInput} -o ${tailwindOutput} --minify`,
+        `"${tailwindBin}" -i "${tailwindInput}" -o "${tailwindOutput}" --minify`,
         { stdio: "inherit" },
     );
 

package.json

@@ -7,6 +7,7 @@
     "private": true,
     "scripts": {
         "test": "jest --forceExit",
+        "test:verbose": "jest --forceExit --verbose",
         "build": "node build.js",
         "lint": "prettier --check .",
         "fmt": "prettier --write .",

script/test

@@ -7,7 +7,13 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 main() {
     cd "$ROOT"
     echo "Running tests..."
-    timeout 30 yarn run test 2>&1
+    timeout 30 yarn run test 2>&1 || {
+        echo "--- Rerunning with --verbose for details ---"
+        timeout 30 yarn run test:verbose 2>&1 || true
+        # Always fail: the first run already proved the tests are broken, so a
+        # flaky pass on the rerun must not turn the build green.
+        exit 1
+    }
 }
 
 main "$@"