--- type: decision tldr: Python 3.8+ stays the template's only scripting runtime; instead of porting every script to bash and PowerShell, the template resolves the interpreter portably, documents install steps per OS, ships a small native fallback for the session-start check, and gives each script-backed skill a documented degraded path. status: accepted decided_on: 2026-09-29 decided_by: Michał Kopeć affects: AGENTS.md, .agents/skills/ckb-lint/, .agents/skills/ckb-retrieve/, .agents/skills/ckb-export-okf/, .agents/skills/ckb-export-starlight/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-reset/, docs/MANUAL.md confidence: 0.85 quality: 0.8 last_updated: 2026-09-29 freshness_window_days: 365 retention: high --- # D-0003 — Python stays the single scripting runtime, with degraded fallbacks rather than parallel ports **Status:** Accepted · **Decided:** 2026-09-29 · **Deciders:** Michał Kopeć ## Context Four skills delegate their deterministic half to a Python script: `lint_report.py` (793 lines), `retrieve_candidates.py` (352), `export_okf.py` (531) and `export_starlight.py` (586) — about 2,300 lines, standard library only. Two more skills (`ckb-upgrade`, `ckb-reset`) used one-line `python3 -c` snippets. Every invocation was spelled `python3`. That fails two groups of users. Those without Python at all — and Rule E runs `lint_report.py --quick` at the start of *every* session, so they hit the failure immediately. And Windows users who *do* have Python, because Windows exposes `python` or the `py` launcher, never `python3`. ## Options considered 1. **Port all four scripts to bash and PowerShell.** Three copies of ~2,300 lines of parsing and ranking logic. Every change to a check or a fusion weight would have to land three times, and the smoke test would need golden output per implementation. Drift between copies is near-certain. 2. **Guidance only.** Detect the missing interpreter, explain how to install it, skip the scripts. Cheap, but the session-start check — the one thing every user runs — would be silently absent for them. 3. **Guidance plus a small native fallback for the session-start check, and a documented degraded path per skill.** The fallback covers the three cheap counts (`malformed`, `past freshness window`, `source drift`) in a few dozen lines each of bash and PowerShell; the smoke test asserts it agrees with the Python reference. Retrieval and full lint fall back to index-first navigation, `grep`, and a manual checklist. The two exporters require Python and stop cleanly. ## Decision Option 3. Concretely: - `AGENTS.md` gains "Scripts and the Python Runtime": resolve `` as the first of `python3`, `python`, `py -3` once per session; on failure say so once and point to "Prerequisites" in `docs/MANUAL.md`. - `ckb-lint` ships `lint_quick.sh` and `lint_quick.ps1` beside `lint_report.py`, plus `references/manual-checklist.md`. - `ckb-retrieve` documents a no-script signal walk. - `ckb-export-okf` and `ckb-export-starlight` state Python as a hard requirement up front. - `ckb-upgrade` and `ckb-reset` drop their inline Python for `sort -V` / `[version]` and `grep -c`. - `tests/smoke.sh` diffs the bash fallback against `--quick`. ## Consequences - The Python scripts remain the reference implementation; the fallbacks are explicitly partial and say so in their output. - Any change to checks 1, 2 or 12 in `lint_report.py` must be mirrored in both fallbacks; the smoke test catches the bash side, and the PowerShell side is reviewed by hand until a Windows runner exists. - Users without Python get a working session start and a slower, scoped lint; they do not get exports until they install Python.