testsAndMisc/docs/superpowers/evidence/pin-all-system-tools-2026-08-04.json

{
  "intent": "Extend the shellcheck version pin from 23fdfcf to every `language: system` tool the gates depend on -- prettier, shfmt and zsh -- so no hook can silently run a different binary on CI than on a developer machine, and so drift is reported at commit time rather than discovered as an unreproducible failure.",
  "scope": [
    ".github/workflows/pre-commit.yml (pin prettier + shfmt, echo zsh version)",
    "linux_configuration/.githooks/lib/common.sh (generalise the drift check to a table)",
    "Non-goal: changing what any hook reports or how any file is formatted",
    "Non-goal: pinning local tool versions, which come from pacman on a rolling distro",
    "Non-goal: adding prettier or shfmt to the CI job's hook run; they remain pre-push and local-git-hook respectively"
  ],
  "changes": [
    "Replaced the single-purpose check_shellcheck_version() with a table-driven check_pinned_tool_versions() over PINNED_TOOL_VERSIONS, covering shellcheck 0.11.0, prettier 3.9.5, shfmt 3.13.1 and zsh 5.9. Each entry names the file pinning the other side, so the warning tells the developer exactly what to update.",
    "Added _tool_version() to normalise the four different version formats: shellcheck's 'version:' line, shfmt's and node's leading 'v', and zsh's second field. Normalising at the source keeps the comparison a plain string match.",
    "zsh is compared on major.minor only, because apt does not allow selecting a patch release on the runner image -- 5.9.2 locally versus 5.9 in CI is not a meaningful divergence and should not produce a permanent warning.",
    "Added a workflow step installing prettier at an exact npm version and shfmt from a checksum-verified release binary, each followed by an assertion that PATH actually resolves to the pinned version rather than to a copy found earlier on PATH.",
    "The zsh install step now echoes 'zsh --version' so a runner image bump appears in the log instead of surfacing as an unexplained parse difference.",
    "Documented in both files WHY prettier and shfmt are pinned despite not running in CI: they rewrite files, so version drift between two developers reformats the repo back and forth."
  ],
  "verification": [
    {
      "command": "python3 -c \"import yaml; yaml.safe_load(open('.github/workflows/pre-commit.yml'))\"",
      "result": "pass",
      "evidence": "Parses cleanly. Step order: checkout, setup-python, Install system dependencies, Install shellcheck (pinned), Install prettier and shfmt (pinned), Install dependencies, Run pre-commit hooks -- every pin lands before the hooks run."
    },
    {
      "command": "the shfmt install steps, executed verbatim in a scratch directory",
      "result": "pass",
      "evidence": "curl fetched shfmt_v3.13.1_linux_amd64; 'sha256sum --check --strict' reported 'shfmt: OK'; the binary reports v3.13.1, so the version gate passes. 'npm view prettier@3.9.5' confirms that exact version resolves from the registry."
    },
    {
      "command": "check_pinned_tool_versions with stubbed prettier 3.0.0 and shfmt v3.0.0 on PATH",
      "result": "pass",
      "evidence": "Emitted a separate warning per tool naming the installed and pinned versions plus both files to update, then the shared 'Results may differ' line. Confirms the 'v' prefix is normalised (v3.0.0 compared as 3.0.0) and that the check reports every drifted tool rather than stopping at the first."
    },
    {
      "command": "check_pinned_tool_versions against the real local toolchain",
      "result": "pass",
      "evidence": "Silent. Local shellcheck 0.11.0, prettier 3.9.5, shfmt v3.13.1 and zsh 5.9.2 all match their pins (zsh on major.minor)."
    },
    {
      "command": "shellcheck linux_configuration/.githooks/lib/common.sh",
      "result": "pass",
      "evidence": "Zero findings. An earlier revision failed with SC1073/SC1072 because a comment line began with '#   shellcheck, zsh --', which shellcheck parsed as a malformed directive; the comment was reworded as prose."
    },
    {
      "command": "source the hook library and inspect verify_toolchain",
      "result": "pass",
      "evidence": "check_pinned_tool_versions is defined and is called from verify_toolchain, so the check runs on every hook invocation."
    },
    {
      "command": "bash ~/.claude/scripts/finish.sh gate ~/testsAndMisc <2 files>",
      "result": "pass",
      "evidence": "FINISH_GATE {\"risk\":\"review\",\"changed_files\":2,\"phase\":\"ok\"} with 1193 Python tests at 100% coverage."
    }
  ],
  "risks": [
    "Four pinned versions now live in two files each and must be bumped together. The local warning exists to surface exactly that, but a developer who ignores it can still drift.",
    "zsh cannot be pinned precisely on the runner image, so it is only compared on major.minor. A patch-level parse difference in zsh would still go unnoticed; the echoed version in the CI log is the mitigation.",
    "CI now depends on the npm registry and a GitHub release asset being reachable. A transient outage fails the workflow rather than silently falling back, which is the intended direction but is a new external dependency.",
    "prettier and shfmt are pinned in a job that does not currently run them, so the pin is unexercised by CI. It protects a future workflow that does run them, and documents the expected version in one place; the real enforcement for these two remains the local drift warning."
  ],
  "rollback": [
    "git revert the commit; the workflow steps are additive and the hook-library change swaps one function for a superset of it.",
    "After reverting, CI returns to the runner image's prettier/shfmt (or none at all) and the local drift warning covers only shellcheck.",
    "Confirm with: pre-commit run --all-files locally, sourcing the hook library to check verify_toolchain still resolves, and the next 'Pre-commit checks' CI run."
  ]
}