[DO NOT MERGE until #3632] Re-add SCSS stylelint hook via project toolchain (DOCS-81) (#3633)

> [!NOTE]
> **Draft, stacked on #3632.** Merge order: **#3632 (unblock) → this**.
Until #3632 merges, its removal commit appears in this diff; afterward
the diff collapses to this PR's change. Please review the CI-workflow
change below — its behavior is proven by this PR's own `pre-commit` run.

The proper fix for the broken SCSS lint hook (DOCS-81), following
#3632's temporary removal.

## Approach

The isolated-node-env hook couldn't resolve
`stylelint-config-standard-scss` in CI because stylelint resolves
`extends` from the **config file's directory** (repo root), not the
hook's environment. This runs the **project's own stylelint** instead:

- **`.pre-commit-config.yaml`** — stylelint hook is now `language:
system`, `entry: node_modules/.bin/stylelint`. It resolves the shared
config from the repo's `node_modules`.
- **`.github/workflows/pre-commit.yaml`** — adds a `setup-node` + `npm
ci --ignore-scripts` step so `node_modules` exists in CI.
`--ignore-scripts` skips the theme's postinstall (for example the Hugo
download), which linting doesn't need.

Unlike the eslint/markdownlint hooks (pre-commit-managed environments),
the SCSS hook needs Node in CI and `npm install` locally. SCSS editors
already run `npm install`; a docs-only contributor never triggers the
hook (it's scoped to `assets/scss/`).

## Verification (local)

- `pre-commit run stylelint` passes on a clean SCSS file and **fails on
a file with a finding** (`color-hex-length`), resolving the config
correctly.
- `actionlint` and `zizmor` pass on the modified workflow (matched the
repo's `cache`-less `setup-node` + zizmor ignore convention).
- YAML valid.

The CI `npm ci` path can only be fully exercised on the runner — this
PR's own `pre-commit` check is that proof.

## Sequencing

Merge order for the chain: **#3632 → this → then #3631** (the
contributor-docs PR, whose docs describe stylelint as an active check).
After #3632 merges I'll rebase this onto `main`.

Fixes DOCS-81.

---
Created in collaboration with Claude Code running Opus 4.8 on
2026-07-23.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: matthewhelmke

.github/workflows/pre-commit.yaml

@@ -58,6 +58,19 @@ jobs:
           restore-keys: |
             pre-commit-
 
+      # The SCSS stylelint hook runs the project's own stylelint
+      # (node_modules/.bin/stylelint) so its shared config, stylelint-config-
+      # standard-scss, resolves from the repo's node_modules. Install just that:
+      # --ignore-scripts skips the theme's postinstall (for example the Hugo
+      # download), which the lint hook does not need.
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        # zizmor: ignore[cache-poisoning] - no cache input is set, so setup-node creates no cache to poison
+        with:
+          node-version: 22
+      - name: Install Node dependencies for the stylelint hook
+        run: npm ci --ignore-scripts
+
       # DO NOT REMOVE: this makes the PR base sha reachable in the shallow
       # clone. Without it the --from-ref/--to-ref range below fails with
       # "fatal: Invalid revision range". If you want to drop this step, you must

.pre-commit-config.yaml

@@ -142,11 +142,18 @@ repos:
         # any local fix would lose on the next sync, so it is not linted here.
         exclude: ^content/platform/chainctl/chainctl-docs/
 
-  # SCSS/stylelint linting is temporarily not wired here. The previous repo-local
-  # node hook could not resolve the shared `extends`
-  # (stylelint-config-standard-scss) in CI: stylelint resolves `extends` from the
-  # config file's directory (repo root), not from the hook's isolated node
-  # environment, and the pre-commit CI has no repo-root node_modules. That made
-  # every PR touching assets/scss fail the required check. It will be re-added to
-  # run against the project's own toolchain, with a Node/npm step in the
-  # pre-commit CI job. Tracking: DOCS-81.
+  # Lint SCSS against .stylelintrc.json using the project's own stylelint
+  # (node_modules/.bin/stylelint), not a pre-commit-managed environment. stylelint
+  # resolves its shared `extends` (stylelint-config-standard-scss) from the repo's
+  # node_modules, so the toolchain must be installed: `npm install` locally and
+  # `npm ci` in CI (see .github/workflows/pre-commit.yaml). --allow-empty-input
+  # keeps the hook green when a commit touches only files excluded by
+  # .stylelintignore.
+  - repo: local
+    hooks:
+      - id: stylelint
+        name: stylelint (SCSS)
+        entry: node_modules/.bin/stylelint
+        language: system
+        args: ['--allow-empty-input']
+        files: ^assets/scss/.*\.(css|scss|sass)$