refactor(scripts): build script hardening (SL-006, 008-013)

scripts/README.md

@@ -0,0 +1,45 @@
+# scripts/ conventions
+
+## Error handling (SL-008)
+
+No single convention is enforced — each script picks whichever fits its
+failure mode, and that's intentional at the current script count (each is a
+single, independently-invoked CI-gate job, not a shared library):
+
+- **`throw new Error(...)`** — for conditions the caller (another script's
+  `import`, or `npm run docs`'s pipeline) should be able to catch, or that
+  indicate a genuinely broken invariant (`bundle.js`'s unbalanced `@layer`
+  block, `version-sync.js`'s pattern-not-found).
+- **`console.error(...)` + `process.exit(1)`** — the CI-gate scripts
+  (`check-*.js`, `audit.js --check`), where the failure is meant to print a
+  human-readable diagnosis and stop the pipeline, not be caught.
+- **Bare `catch { ... }`** (no rethrow) — best-effort operations where
+  failure is an expected, non-fatal branch (e.g. "file doesn't exist yet,
+  fall back to a default").
+
+Revisit this if the script count grows enough that the inconsistency itself
+becomes confusing; not worth enforcing for ~17 independent scripts.
+
+## CLI flag parsing (SL-009)
+
+Every script hand-rolls `process.argv.includes('--flag')` checks; there's no
+shared arg-parsing helper or `--help` output. Fine at the current ~1-2
+flags per script — revisit if any script's flag count grows past that.
+
+## Environment variables (SL-011)
+
+| Var | Read by | Purpose |
+|---|---|---|
+| `SLASHED_ROOT` | `check-version-sync.js` | Override the repo root (test-only — lets the version-sync test suite point at a fixture tree instead of the real repo). |
+| `GITHUB_REF`, `GITHUB_REF_NAME` | `bundle.js` | CI-only — used to detect whether the current run is on a release tag, for badge-stamping. |
+| `GITHUB_BASE_REF` | `check-token-registry.js` | CI-only — the PR's target branch, used to diff the registry against the base ref instead of just the working tree. |
+
+## `execSync(cmd, { shell: true })` (SL-013)
+
+`check-artifacts.js`'s `run()` helper and `changelog-release.js` both shell
+out with a command string. In both cases `cmd` is either a hardcoded git
+command or sourced from `scripts/artifacts.json`, a repo-committed config
+file — not attacker-controlled input today. The pattern does grant full
+shell execution to whatever string ends up in `artifacts.json`'s
+`buildCmd` field, though, so treat new entries there with the same care as
+any other code change, not as inert config.