- 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>
3.7 KiB
3.7 KiB
| type | tldr | status | decided_on | decided_by | affects | confidence | quality | last_updated | freshness_window_days | retention |
|---|---|---|---|---|---|---|---|---|---|---|
| decision | 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. | accepted | 2026-09-29 | Michał Kopeć | 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 | 0.85 | 0.8 | 2026-09-29 | 365 | 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
- 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.
- 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.
- 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.mdgains "Scripts and the Python Runtime": resolve<python>as the first ofpython3,python,py -3once per session; on failure say so once and point to "Prerequisites" indocs/MANUAL.md.ckb-lintshipslint_quick.shandlint_quick.ps1besidelint_report.py, plusreferences/manual-checklist.md.ckb-retrievedocuments a no-script signal walk.ckb-export-okfandckb-export-starlightstate Python as a hard requirement up front.ckb-upgradeandckb-resetdrop their inline Python forsort -V/[version]andgrep -c.tests/smoke.shdiffs 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.pymust 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.