# HK Windows Step Status (2026-04-11)

This document records the hk steps that were modified during the recent Windows compatibility fix loop.

> [!NOTE]
> The legacy prek-generated configuration and its `pre-commit-config` step were
> removed after this snapshot. HK is now the sole Git hook and lint runner.

## Status Legend

- **Fully resolved**: Cross-platform execution issue is fixed and no compatibility gap is currently known.
- **Mitigated**: Main blocker is removed, but behavior differs from default upstream behavior or has a known trade-off.
- **Partially resolved**: Invocation/path-quoting issue is fixed, but the step still fails due to repository content debt (format/lint findings).
- **Pending**: Not fixed yet in this loop.

## Step-by-step Status

| Step                                  | Status             | What was changed                                                                                                                                                                                     | Verified result                                                                                                                                    | Remaining pitfall                                                                                                                                                                           |
| ------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actionlint`                          | **Mitigated**      | Replaced builtin invocation with `python eng/scripts/hk_actionlint.py {{files}}` in `hk.pkl`. Added per-file start timestamp, heartbeat, timeout, and process-tree kill on timeout.                  | `hk check --all --check --step actionlint --profile small --no-progress` passed on Windows (19/19 files) with both 600s and 120s timeout settings. | `shellcheck` and `pyflakes` integrations are disabled by default (`-shellcheck=` and `-pyflakes=`). This avoids hangs, but is not full parity with default actionlint integration behavior. |
| `pkl-eval` (root monorepo)            | **Fully resolved** | Added `src/private/lib/hk/steps/PklEval.pkl`; wired in `src/private/lib/hk/Steps.pkl`; switched root `hk.pkl` to `Steps.pkl_eval`; introduced `eng/scripts/hk_pkl_eval.py` for robust path handling. | Full run log contains `✔ pkl-eval`.                                                                                                                | No known Windows invocation gap currently.                                                                                                                                                  |
| `pkl-eval` (`hexo-renderer-asciidoc`) | **Fully resolved** | Added `pkl_eval` step in `src/public/lib/hexo-renderer-asciidoc/steps.pkl` and switched `src/public/lib/hexo-renderer-asciidoc/hk.pkl` from builtin pkl to custom step.                              | Command wiring verified in config; behavior aligns with root wrapper-based invocation.                                                             | No known Windows invocation gap currently.                                                                                                                                                  |
| `pkl-format`                          | **Fully resolved** | Switched to wrapper-based invocation in `src/private/lib/hk/steps/PklFormat.pkl`: `python eng/scripts/hk_exec.py pkl format ... -- {{files}}`.                                                       | `hk check --all --check --step pkl-format --profile small --no-progress` passes on Windows.                                                        | No known Windows invocation gap currently.                                                                                                                                                  |
| `typos`                               | **Mitigated**      | Switched to wrapper-based invocation in `src/private/lib/hk/steps/Typos.pkl` and added `--force-exclude` so `.typos.toml` exclusions remain effective when hk passes explicit file lists.            | `hk check --all --check --step typos --profile small --no-progress` returns exit code `0` on Windows.                                              | Uses a targeted file-level exclude list for the noisiest imported `src/public/lib/Hjg.Pngcs` sources instead of disabling typo checks for the whole subtree.                                |
| `editorconfig-check`                  | **Fully resolved** | Root `hk.pkl` calls `python eng/scripts/hk_exec.py editorconfig-checker --disable-indent-size -- {{files}}`.                                                                                         | `hk check --all --check --step editorconfig-check --profile small --no-progress` returns exit code `0` on Windows.                                 | No known Windows invocation gap currently.                                                                                                                                                  |
| `shellcheck`                          | **Fully resolved** | Replaced builtin with wrapper command in `hk.pkl`: `python eng/scripts/hk_exec.py shellcheck -- {{files}}`.                                                                                          | Full run log contains `✔ shellcheck`.                                                                                                              | No known Windows invocation gap currently.                                                                                                                                                  |
| `shfmt`                               | **Fully resolved** | Replaced builtin with wrapper command in `hk.pkl` for both check/fix, with explicit globs and `--` separation.                                                                                       | `hk check --all --check --step shfmt --profile small --no-progress` passes after step-local `hk fix` on Windows.                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `markdown-prettier`                   | **Fully resolved** | Replaced builtin prettier step with wrapper command in `hk.pkl`, then fixed `hk_exec.py` to split command/files at the **last** `--` (required for `pnpm exec -- prettier ... -- {{files}}`).        | `hk check --all --check --step markdown-prettier --profile small --no-progress` passes on Windows after step-local `hk fix`.                       | No known Windows invocation/parsing gap currently.                                                                                                                                          |
| `yaml-prettier`                       | **Fully resolved** | Replaced builtin prettier step with wrapper command in `hk.pkl`, then fixed `hk_exec.py` last-`--` parsing issue (same root cause as markdown-prettier).                                             | `hk check --all --check --step yaml-prettier --profile small --no-progress` passes on Windows after step-local `hk fix`.                           | No known Windows invocation/parsing gap currently.                                                                                                                                          |
| `ruff_format`                         | **Fully resolved** | Replaced builtin invocation in `hk.pkl` with wrapper command: `python eng/scripts/hk_exec.py uv run ruff format --quiet --force-exclude ... -- {{files}}`.                                           | `hk check --all --check --step ruff_format --profile small --no-progress` passes after step-local `hk fix` on Windows.                             | No known Windows invocation gap currently.                                                                                                                                                  |
| `nwa` (subproject helper redirection) | **Fully resolved** | In `src/public/lib/hexo-renderer-asciidoc/steps.pkl`, changed `fix` script redirection to platform-specific form (`2>/dev/null` on Linux, `2>NUL` on Windows).                                       | Config-level compatibility fix applied.                                                                                                            | No known redirection compatibility gap for this change.                                                                                                                                     |
| `ruff`                                | **Fully resolved** | Replaced `Builtins.ruff` with `prefix` with wrapper command in `hk.pkl`: `python eng/scripts/hk_exec.py uv run ruff check --force-exclude -- {{files}}`.                                             | Windows `hk check --all` now correctly detects Python lint violations (previously E902 false-pass due to quoted paths).                            | No known Windows invocation gap currently.                                                                                                                                                  |
| `biome`                               | **Fully resolved** | Replaced `Builtins.biome` with `prefix` with wrapper command in `hk.pkl`: `python eng/scripts/hk_exec.py pnpm exec -- biome check --no-errors-on-unmatched -- {{files}}`.                            | Windows `hk check --all` now correctly detects JS/TS lint violations (previously silent false-pass due to quoted paths).                           | No known Windows invocation gap currently.                                                                                                                                                  |
| `json-biome`                          | **Fully resolved** | Same pattern as `biome`: replaced `Builtins.biome` with wrapper command for JSON/JSONC files.                                                                                                        | Windows `hk check --all` now correctly detects JSON formatting violations.                                                                         | No known Windows invocation gap currently.                                                                                                                                                  |
| `markdownlint-cli2`                   | **Fully resolved** | Replaced `Steps.markdownlint_cli2` with `prefix` with wrapper command: `python eng/scripts/hk_exec.py pnpm exec -- markdownlint-cli2 -- {{files}}`.                                                  | Windows `hk check --all` runs markdownlint-cli2 with properly unquoted paths.                                                                      | No known Windows invocation gap currently.                                                                                                                                                  |
| `toml-taplo-check`                    | **Fully resolved** | Replaced `Builtins.taplo` with `prefix` with wrapper command: `python eng/scripts/hk_exec.py pnpm exec -- taplo check -- {{files}}`.                                                                 | Windows `hk check --all` runs taplo check with properly unquoted paths.                                                                            | No known Windows invocation gap currently.                                                                                                                                                  |
| `toml-taplo-format`                   | **Fully resolved** | Replaced raw `taplo format` commands with wrapper commands: `python eng/scripts/hk_exec.py pnpm exec -- taplo format --check -- {{files}}`.                                                          | Windows `hk check --all` now correctly detects TOML formatting violations.                                                                         | No known Windows invocation gap currently.                                                                                                                                                  |
| `hadolint`                            | **Fully resolved** | Replaced `Builtins.hadolint` with wrapper command: `python eng/scripts/hk_exec.py hadolint -- {{files}}`.                                                                                            | Currently skipped (no Dockerfile in repo), but wrapper ensures correct path handling when Dockerfiles are added.                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `dotenv-linter`                       | **Fully resolved** | Overrode `Steps.dotenv_linter` check/fix with wrapper commands: `python eng/scripts/hk_exec.py dotenv-linter check -- {{files}}`.                                                                    | Windows `hk check --all` runs dotenv-linter with properly unquoted paths.                                                                          | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: json-biome`                    | **Fully resolved** | In `hexo-renderer-asciidoc/hk.pkl`, replaced `Builtins.biome` with wrapper command for JSON files.                                                                                                   | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: yaml-prettier`                 | **Fully resolved** | In `hexo-renderer-asciidoc/hk.pkl`, replaced `Builtins.prettier` with wrapper command for YAML files.                                                                                                | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: markdown-prettier`             | **Fully resolved** | In `hexo-renderer-asciidoc/hk.pkl`, replaced `Builtins.prettier` with wrapper command for Markdown files.                                                                                            | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: js-biome`                      | **Fully resolved** | In `hexo-renderer-asciidoc/hk.pkl`, replaced `Builtins.biome` with wrapper command for JS/TS files.                                                                                                  | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: markdownlint-cli2`             | **Fully resolved** | In `hexo-renderer-asciidoc/steps.pkl`, wrapped `markdownlint-cli2` commands with `hk_exec.py`.                                                                                                       | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: typos`                         | **Fully resolved** | In `hexo-renderer-asciidoc/steps.pkl`, wrapped `typos` commands with `hk_exec.py` and added `--force-exclude`.                                                                                       | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |
| `hexo: pklFormat`                     | **Fully resolved** | In `hexo-renderer-asciidoc/steps.pkl`, wrapped `pkl format` commands with `hk_exec.py`.                                                                                                              | Config-level fix applied; consistent with root monorepo pattern.                                                                                   | No known Windows invocation gap currently.                                                                                                                                                  |

## Shared helper scripts introduced in this loop

- `eng/scripts/hk_exec.py`
    - Normalizes quoted file paths and safely forwards command + file args.
    - Adds per-file start time, heartbeat, timeout, and timeout process-tree kill (`HK_EXEC_TIMEOUT_SECONDS`, `HK_EXEC_HEARTBEAT_SECONDS`, `HK_EXEC_PER_FILE`).
    - Uses the **last** `--` as file separator so commands like `pnpm exec -- prettier --check -- {{files}}` are parsed correctly.
    - Used by `typos`, `pkl-format`, `editorconfig-check`, `shellcheck`, `shfmt`, `markdown-prettier`, `yaml-prettier`, `ruff_format`, `ruff`, `biome`, `json-biome`, `markdownlint-cli2`, `toml-taplo-check`, `toml-taplo-format`, `hadolint`, `dotenv-linter`.

- `eng/scripts/hk_pkl_eval.py`
    - Evaluates pkl files one by one, preserving failure output and handling quoted paths.

- `eng/scripts/hk_actionlint.py`
    - Adds file-level observability and timeout controls.
    - Supports env tuning:
        - `HK_ACTIONLINT_TIMEOUT_SECONDS`
        - `HK_ACTIONLINT_HEARTBEAT_SECONDS`
        - `HK_ACTIONLINT_SHELLCHECK`
        - `HK_ACTIONLINT_PYFLAKES`

## Still pending (not fixed in this loop)

No Windows execution blockers are currently pending for this loop.

Latest end-to-end verification on Windows (2026-04-11):

- `mise exec -- hk check --no-progress --no-fail-fast --all` → **exit code 1** (pre-existing lint violations detected; no execution failures)
- All steps execute correctly; failures are legitimate code quality violations, not path/quoting issues.
- Previously, steps using `Builtins.*` with `prefix` would false-pass on Windows due to quoted file paths.

## Known trade-offs (release checklist)

- `actionlint`
    - Current mode disables integrated `shellcheck`/`pyflakes` by default in `eng/scripts/hk_actionlint.py`.
    - Before release hardening, decide whether to re-enable one or both integrations in CI (with timeout safeguards retained).

- `typos`
    - Current mode uses `--force-exclude` in `src/private/lib/hk/steps/Typos.pkl` and a targeted file-level exclude list for the noisiest `src/public/lib/Hjg.Pngcs` sources in `.typos.toml`.
    - If upstream-import exclusions are tightened later, re-run `hk check --all --check --step typos --profile small --no-progress` to verify false positives stay manageable.

## Notes

- This file distinguishes **execution compatibility** from **repository lint/format debt**.
- A step can be marked “resolved” for Windows execution while still failing on repository content rules.
