ckb/docs/decisions/0003-python-runtime-with-degraded-fallbacks.md
Michał Kopeć 27d84fe008 Template 1.11.0: optional Python with degraded fallbacks; lint check 13 per-block Crux matching
- D-0003: <python> interpreter resolution, per-OS install guide, lint_quick.sh/.ps1
  session-start fallback, manual lint checklist, no-script retrieval path,
  exporters declare Python a hard requirement
- Lint check 13 pairs each Crux quote block with the attribution under it, so a
  multi-source Crux no longer cross-fails; fixture KB gains a second source
- Session summaries for 2026-09-29 and 2026-10-01

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-01 21:26:43 +02:00

73 lines
3.7 KiB
Markdown

---
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 `<python>`
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.