- 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>
73 lines
3.7 KiB
Markdown
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.
|