ckb/docs/decisions/0003-python-runtime-with-degraded-fallbacks.md
Michał Kopeć 8415004031 Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019)
Adds the `1.x` release channel (fixes only, last line with PowerShell
support) to every channel table, and makes ckb-upgrade stop and ask before
crossing a major version, offering the maintenance branch instead.
D-0019 records the 2.0 plan: drop PowerShell, scripts stay in Python.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:47:37 +01:00

3.9 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ć

The PowerShell half (lint_quick.ps1, the [version] comparison) was dropped in template 2.0.0 by D-0019. Everything else stands; 1.x keeps it on the 1.x branch.

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.